[RFC 5/5] perf, tool: Add events specification doc

[Jiri Olsa <jolsa@redhat.com>]

Adding perf-events.txt with description of event specification.
Linked from perf-stat.txt and perf-record.txt.

Signed-off-by: Jiri Olsa <jolsa@redhat.com>
---
 tools/perf/Documentation/perf-events.txt |  182 ++++++++++++++++++++++++++++++
 tools/perf/Documentation/perf-record.txt |    2 +-
 tools/perf/Documentation/perf-stat.txt   |    2 +-
 3 files changed, 184 insertions(+), 2 deletions(-)
 create mode 100644 tools/perf/Documentation/perf-events.txt

diff --git a/tools/perf/Documentation/perf-events.txt b/tools/perf/Documentation/perf-events.txt
new file mode 100644
index 0000000..172947d
--- /dev/null
+++ b/tools/perf/Documentation/perf-events.txt
@@ -0,0 +1,182 @@
+perf-events(7)
+==============
+
+NAME
+----
+perf-events - Description of perf event specification
+
+SYNOPSIS
+--------
+[verse]
+'perf record' [-e <EVENTS> | --event=EVENTS]
+'perf stat'   [-e <EVENTS> | --event=EVENTS]
+
+EVENT SYNTAX
+------------
+.......................................................................................
+events:                         events ',' event | event
+
+event:                          event_def ':' [ukhp]{1,5}
+
+event_def:                      event_pmu |
+                                event_legacy_symbol |
+                                event_legacy_cache sep_dc |
+                                event_legacy_mem |
+                                event_legacy_tracepoint sep_dc |
+                                event_legacy_numeric sep_dc |
+                                event_legacy_raw sep_dc
+
+event_pmu:                      pmu_name '/' event_config '/'
+
+event_legacy_symbol:            symbol '/' event_config '/' |
+                                symbol
+
+symbol:                         cpu-cycles | cycles |
+                                stalled-cycles-frontend | idle-cycles-frontend |
+                                stalled-cycles-backend | idle-cycles-backend |
+                                instructions |
+                                cache-references |
+                                cache-misses |
+                                branch-instructions | branches |
+                                branch-misses |
+                                bus-cycles |
+                                cpu-clock |
+                                task-clock |
+                                page-faults | faults |
+                                minor-faults |
+                                major-faults |
+                                context-switches | cs |
+                                cpu-migrations | migrations |
+                                alignment-faults |
+                                emulation-faults
+
+event_legacy_cache:             cache_type '-' cache_op_result '-' cache_op_result |
+                                cache_type '-' cache_op_result |
+                                cache_type
+
+cache_type:                     L1-dcache | l1-d | l1d | L1-data |
+                                L1-icache | l1-i | l1i | L1-instruction |
+                                LLC | L2 |
+                                dTLB | d-tlb | Data-TLB |
+                                iTLB | i-tlb | Instruction-TLB |
+                                branch | branches | bpu | btb | bpc |
+                                node
+
+cache_op_result:                load | loads | read |
+                                store | stores | write |
+                                prefetch | prefetches |
+                                speculative-read | speculative-load |
+                                refs | Reference | ops | access |
+                                misses | miss
+
+event_legacy_mem:               'mem:' value ':' [rwx]
+
+event_legacy_tracepoint:        subsystem ':' tracepoint
+
+event_legacy_numeric:           value ':' value
+
+event_legacy_raw:               'r' value
+
+event_config:                   event_config ',' event_term |
+                                event_term
+
+event_term:                     name '=' str |
+                                name '=' value |
+                                event_term_list
+
+event_term_list:                event_term_list '|' event_term_elem |
+                                event_term_elem '|' event_term_elem
+
+event_term_elem:                name | value
+.......................................................................................
+
+
+PMU EVENT
+---------
+The kernel PMU exports its event format description via sysfs.
+It's located at following path:
+
+        ${sysfs_mount}/bus/event_source/devices/${pmu}/format
+
+The format directory contains files representing events terms.
+Each event term file contains information describing how to
+apply the term value into perf event config eg:
+
+        $ cat /sys/bus/event_source/devices/cpu/format/umask
+        config:8-15
+
+says term 'umask' defines bits 8 to 15 inside config value of
+the perf event.
+
+Example:
+        cpu/event=0xb7,umask=0x01,offcore_rsp=0x500b/
+
+
+SYMBOLIC EVENT
+--------------
+empty
+
+HW CACHE EVENT
+--------------
+empty
+
+BREAKPOINT EVENT
+----------------
+The breakpoint event allows to create a breakpoint inside traced
+application. An event is generated in case the the breakpoint is
+trigered.
+
+NUMERIC EVENT
+-------------
+empty
+
+RAW EVENT
+---------
+Even when an event is not available in a symbolic form within perf
+right now, it can be encoded in a per processor specific way.
+
+For instance For x86 CPUs NNN represents the raw register encoding with
+the layout of IA32_PERFEVTSELx MSRs (see [Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide] Figure 30-1 Layout
+of IA32_PERFEVTSELx MSRs) or AMD's PerfEvtSeln (see [AMD64 Architecture Programmer’s Manual Volume 2: System Programming], Page 344,
+Figure 13-7 Performance Event-Select Register (PerfEvtSeln)).
+
+Example:
+
+If the Intel docs for a QM720 Core i7 describe an event as:
+
+  Event  Umask  Event Mask
+  Num.   Value  Mnemonic    Description                        Comment
+
+  A8H      01H  LSD.UOPS    Counts the number of micro-ops     Use cmask=1 and
+                            delivered by loop stream detector  invert to count
+                                                               cycles
+
+raw encoding of 0x1A8 can be used:
+
+ perf stat -e r1a8 -a sleep 1
+ perf record -e r1a8 ...
+
+You should refer to the processor specific documentation for getting these
+details. Some of them are referenced in the SEE ALSO section below.
+
+EVENT MODIFIERS
+---------------
+Events can optionally have a modifer by appending a colon and one or
+more modifiers.  Modifiers allow the user to restrict when events are
+counted with 'u' for user-space, 'k' for kernel, 'h' for hypervisor.
+Additional modifiers are 'G' for guest counting (in KVM guests) and 'H'
+for host counting (not in KVM guests).
+
+The 'p' modifier can be used for specifying how precise the instruction
+address should be. The 'p' modifier is currently only implemented for
+Intel PEBS and 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
+
+The PEBS implementation now supports up to 2.
+
+SEE ALSO
+--------
+linkperf:perf-stat[1], linkperf:perf-record[1]
diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
index a1386b2..5a96fba 100644
--- a/tools/perf/Documentation/perf-record.txt
+++ b/tools/perf/Documentation/perf-record.txt
@@ -184,4 +184,4 @@ Note that this feature may not be available on all processors.
 
 SEE ALSO
 --------
-linkperf:perf-stat[1], linkperf:perf-list[1]
+linkperf:perf-stat[1], linkperf:perf-list[1], linkperf:perf-events[7]
diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
index 2fa173b..5008992 100644
--- a/tools/perf/Documentation/perf-stat.txt
+++ b/tools/perf/Documentation/perf-stat.txt
@@ -130,4 +130,4 @@ $ perf stat -- make -j
 
 SEE ALSO
 --------
-linkperf:perf-top[1], linkperf:perf-list[1]
+linkperf:perf-top[1], linkperf:perf-list[1], linkperf:perf-events[7]
-- 
1.7.6.5