[PATCH 1/2] perf, tools: Document event specifications better

[Andi Kleen]

From: Andi Kleen <ak@xxxxxxxxxxxxxxx>

Document some undocumented features for specifying events in the perf
list manpage:

- Event groups
- Leader sampling
- How to specify raw PMU events in the new syntax

Signed-off-by: Andi Kleen <ak@xxxxxxxxxxxxxxx>
---
 tools/perf/Documentation/perf-list.txt | 49 ++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
index 79483f4..240c8ff 100644
--- a/tools/perf/Documentation/perf-list.txt
+++ b/tools/perf/Documentation/perf-list.txt
@@ -91,6 +91,22 @@ raw encoding of 0x1A8 can be used:
 You should refer to the processor specific documentation for getting these
 details. Some of them are referenced in the SEE ALSO section below.
 
+ARBITRARY PMUS
+--------------
+
+perf also supports an extended syntax for specifying raw parameters
+to PMUs. Using this typically requires looking up the specific event
+in the CPU vendor specific documentation.
+
+The available PMUs and their raw parameters can be listed with
+
+  ls /sys/devices/*/format
+
+For example the raw event LSD.UOPS core pmu event above could
+be specified as
+
+  perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=1/ ...
+
 PARAMETERIZED EVENTS
 --------------------
 
@@ -104,6 +120,39 @@ also be supplied. For example:
 
   perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
 
+EVENT GROUPS
+------------
+
+Perf supports time based multiplexing of events, when the number of events
+active exceeds the number of hardware performance counters. Multiplexing
+can cause measurement errors when the workload changes its execution
+profile.
+
+When metrics are computed using formulas from event counts, it is useful to
+ensure some events are always measured together as a group to minimize multiplexing
+errors. Event groups can be specified using { }.
+
+  perf stat -e '{instructions,cycles}' ...
+
+When too many events are specified in the group perf the event will not
+be measured. The number of available performance counters depend on the CPU.
+For example Intel Core CPUs have typically four generic performance counters
+for the core, plus a number of specialized fixed counters.
+
+Events from multiple different PMUs cannot be mixed in a group.
+
+LEADER SAMPLING
+---------------
+
+perf also supports group leader sampling using the :S specifier.
+
+  perf record -e '{cycles,instructions}:S' ...
+  perf report --group
+
+Normally all events in a event group sample, but with :S only
+the first event (the leader) samples, and it only reads the values of the
+other events in the group.
+
 OPTIONS
 -------
 
-- 
2.5.5