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

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

[Andi Kleen]

From: Andi Kleen <ak@linux.intel.com>

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@linux.intel.com>
---
 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

[PATCH 2/2] perf, tools: Fix documentation of :ppp in perf list

[Andi Kleen]

From: Andi Kleen <ak@linux.intel.com>

Correctly document what is implemented for :ppp on Intel CPUs in
recent kernels.

Signed-off-by: Andi Kleen <ak@linux.intel.com>
---
 tools/perf/Documentation/perf-list.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
index 240c8ff..fbe52ac 100644
--- a/tools/perf/Documentation/perf-list.txt
+++ b/tools/perf/Documentation/perf-list.txt
@@ -40,10 +40,12 @@ address should be. The 'p' modifier can be specified multiple times:
  0 - SAMPLE_IP can have arbitrary skid
  1 - SAMPLE_IP must have constant skid
  2 - SAMPLE_IP requested to have 0 skid
- 3 - SAMPLE_IP must have 0 skid
+ 3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
+     sample shadowing effects.
 
 For Intel systems precise event sampling is implemented with PEBS
-which supports up to precise-level 2.
+which supports up to precise-level 2, and precise level 3 for
+some special cases
 
 On AMD systems it is implemented using IBS (up to precise-level 2).
 The precise modifier works with event types 0x76 (cpu-cycles, CPU
-- 
2.5.5

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

[Jiri Olsa]

On Mon, Mar 21, 2016 at 08:56:32AM -0700, Andi Kleen wrote:

SNIP

> +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
                                                   ^^^^^^^^^^^^^^
                                        maybe:    'none of them' will be meassured.



> +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.

hum, but we allow that right?

only when there's mixture of SW and HW events we move
it all silently under HW event context

jirka

Re: [PATCH 2/2] perf, tools: Fix documentation of :ppp in perf list

[Jiri Olsa]

On Mon, Mar 21, 2016 at 08:56:33AM -0700, Andi Kleen wrote:
> From: Andi Kleen <ak@linux.intel.com>
> 
> Correctly document what is implemented for :ppp on Intel CPUs in
> recent kernels.
> 
> Signed-off-by: Andi Kleen <ak@linux.intel.com>

Acked-by: Jiri Olsa <jolsa@kernel.org>

thanks,
jirka

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

[Peter Zijlstra]

On Tue, Mar 22, 2016 at 08:57:35AM +0100, Jiri Olsa wrote:
> > +Events from multiple different PMUs cannot be mixed in a group.
> 
> hum, but we allow that right?
> 
> only when there's mixture of SW and HW events we move
> it all silently under HW event context

I forgot the exact details, but we put some tight restrictions on it.

SW events can indeed be added to regular HW events, and could with some
careful work be allowed on most other groups as well (but IIRC we don't
currently allow them onto things like uncore etc..).

[tip:perf/urgent] perf list: Fix documentation of :ppp

[tip-bot for Andi Kleen]

Commit-ID:  4ca0d8193f8b6b2c74d05d9bbcbaa99fdd553503
Gitweb:     http://git.kernel.org/tip/4ca0d8193f8b6b2c74d05d9bbcbaa99fdd553503
Author:     Andi Kleen <ak@linux.intel.com>
AuthorDate: Mon, 21 Mar 2016 08:56:33 -0700
Committer:  Arnaldo Carvalho de Melo <acme@redhat.com>
CommitDate: Tue, 22 Mar 2016 10:01:45 -0300

perf list: Fix documentation of :ppp

Correctly document what is implemented for :ppp on Intel CPUs in recent
kernels.

Signed-off-by: Andi Kleen <ak@linux.intel.com>
Acked-by: Jiri Olsa <jolsa@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Link: http://lkml.kernel.org/r/1458575793-12091-2-git-send-email-andi@firstfloor.org
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
---
 tools/perf/Documentation/perf-list.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
index 79483f4..ec723d0 100644
--- a/tools/perf/Documentation/perf-list.txt
+++ b/tools/perf/Documentation/perf-list.txt
@@ -40,10 +40,12 @@ address should be. The 'p' modifier can be specified multiple times:
  0 - SAMPLE_IP can have arbitrary skid
  1 - SAMPLE_IP must have constant skid
  2 - SAMPLE_IP requested to have 0 skid
- 3 - SAMPLE_IP must have 0 skid
+ 3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
+     sample shadowing effects.
 
 For Intel systems precise event sampling is implemented with PEBS
-which supports up to precise-level 2.
+which supports up to precise-level 2, and precise level 3 for
+some special cases
 
 On AMD systems it is implemented using IBS (up to precise-level 2).
 The precise modifier works with event types 0x76 (cpu-cycles, CPU