Messages in this thread Patch in this message | | | From | Jiri Olsa <> | Subject | [RFC 5/5] perf, tool: Add events specification doc | Date | Wed, 28 Mar 2012 17:55:53 +0200 |
| |
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 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
| |