diff options
Diffstat (limited to 'tools/perf/Documentation')
| -rw-r--r-- | tools/perf/Documentation/android.txt | 16 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-annotate.txt | 7 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-buildid-cache.txt | 3 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-data.txt | 4 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-mem.txt | 3 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-probe.txt | 32 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-record.txt | 32 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-report.txt | 7 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-script.txt | 31 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-stat.txt | 32 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf-test.txt | 4 | ||||
| -rw-r--r-- | tools/perf/Documentation/perf.data-file-format.txt | 442 |
12 files changed, 588 insertions, 25 deletions
diff --git a/tools/perf/Documentation/android.txt b/tools/perf/Documentation/android.txt index 8484c3a04a6a..24a59998fc91 100644 --- a/tools/perf/Documentation/android.txt +++ b/tools/perf/Documentation/android.txt @@ -12,14 +12,14 @@ Set the NDK variable to point to the path where you installed the NDK: 2. Set cross-compiling environment variables for NDK toolchain and sysroot. For arm: - export NDK_TOOLCHAIN=${NDK}/toolchains/arm-linux-androideabi-4.6/prebuilt/linux-x86/bin/arm-linux-androideabi- - export NDK_SYSROOT=${NDK}/platforms/android-9/arch-arm + export NDK_TOOLCHAIN=${NDK}/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin/arm-linux-androideabi- + export NDK_SYSROOT=${NDK}/platforms/android-24/arch-arm For x86: - export NDK_TOOLCHAIN=${NDK}/toolchains/x86-4.6/prebuilt/linux-x86/bin/i686-linux-android- - export NDK_SYSROOT=${NDK}/platforms/android-9/arch-x86 + export NDK_TOOLCHAIN=${NDK}/toolchains/x86-4.9/prebuilt/linux-x86_64/bin/i686-linux-android- + export NDK_SYSROOT=${NDK}/platforms/android-24/arch-x86 -This method is not working for Android NDK versions up to Revision 8b. -perf uses some bionic enhancements that are not included in these NDK versions. +This method is only tested for Android NDK versions Revision 11b and later. +perf uses some bionic enhancements that are not included in prior NDK versions. You can use method (b) described below instead. (b). Use the Android source tree @@ -49,9 +49,9 @@ II. Compile perf for Android ------------------------------------------------ You need to run make with the NDK toolchain and sysroot defined above: For arm: - make ARCH=arm CROSS_COMPILE=${NDK_TOOLCHAIN} CFLAGS="--sysroot=${NDK_SYSROOT}" + make WERROR=0 ARCH=arm CROSS_COMPILE=${NDK_TOOLCHAIN} EXTRA_CFLAGS="-pie --sysroot=${NDK_SYSROOT}" For x86: - make ARCH=x86 CROSS_COMPILE=${NDK_TOOLCHAIN} CFLAGS="--sysroot=${NDK_SYSROOT}" + make WERROR=0 ARCH=x86 CROSS_COMPILE=${NDK_TOOLCHAIN} EXTRA_CFLAGS="-pie --sysroot=${NDK_SYSROOT}" III. Install perf ----------------------------------------------- diff --git a/tools/perf/Documentation/perf-annotate.txt b/tools/perf/Documentation/perf-annotate.txt index 778f54d4d0bd..8ffbd272952d 100644 --- a/tools/perf/Documentation/perf-annotate.txt +++ b/tools/perf/Documentation/perf-annotate.txt @@ -61,6 +61,13 @@ OPTIONS --stdio:: Use the stdio interface. +--stdio-color:: + 'always', 'never' or 'auto', allowing configuring color output + via the command line, in addition to via "color.ui" .perfconfig. + Use '--stdio-color always' to generate color even when redirecting + to a pipe or file. Using just '--stdio-color' is equivalent to + using 'always'. + --tui:: Use the TUI interface. Use of --tui requires a tty, if one is not present, as when piping to other commands, the stdio interface is used. This interfaces starts by centering on the line with more diff --git a/tools/perf/Documentation/perf-buildid-cache.txt b/tools/perf/Documentation/perf-buildid-cache.txt index dd07b55f58d8..058064db39d2 100644 --- a/tools/perf/Documentation/perf-buildid-cache.txt +++ b/tools/perf/Documentation/perf-buildid-cache.txt @@ -15,6 +15,9 @@ DESCRIPTION This command manages the build-id cache. It can add, remove, update and purge files to/from the cache. In the future it should as well set upper limits for the space used by the cache, etc. +This also scans the target binary for SDT (Statically Defined Tracing) and +record it along with the buildid-cache, which will be used by perf-probe. +For more details, see linkperf:perf-probe[1]. OPTIONS ------- diff --git a/tools/perf/Documentation/perf-data.txt b/tools/perf/Documentation/perf-data.txt index be8fa1a0a97e..f0796a47dfa3 100644 --- a/tools/perf/Documentation/perf-data.txt +++ b/tools/perf/Documentation/perf-data.txt @@ -34,6 +34,10 @@ OPTIONS for 'convert' --verbose:: Be more verbose (show counter open errors, etc). +--all:: + Convert all events, including non-sample events (comm, fork, ...), to output. + Default is off, only convert samples. + SEE ALSO -------- linkperf:perf[1] diff --git a/tools/perf/Documentation/perf-mem.txt b/tools/perf/Documentation/perf-mem.txt index 1d6092c460dd..73496320fca3 100644 --- a/tools/perf/Documentation/perf-mem.txt +++ b/tools/perf/Documentation/perf-mem.txt @@ -56,6 +56,9 @@ OPTIONS --all-user:: Configure all used events to run in user space. +--ldload:: + Specify desired latency for loads event. + SEE ALSO -------- linkperf:perf-record[1], linkperf:perf-report[1] diff --git a/tools/perf/Documentation/perf-probe.txt b/tools/perf/Documentation/perf-probe.txt index 3a8a9ba2b041..736da44596e4 100644 --- a/tools/perf/Documentation/perf-probe.txt +++ b/tools/perf/Documentation/perf-probe.txt @@ -67,7 +67,10 @@ OPTIONS -l:: --list[=[GROUP:]EVENT]:: - List up current probe events. This can also accept filtering patterns of event names. + List up current probe events. This can also accept filtering patterns of + event names. + When this is used with --cache, perf shows all cached probes instead of + the live probes. -L:: --line=:: @@ -109,6 +112,12 @@ OPTIONS Dry run. With this option, --add and --del doesn't execute actual adding and removal operations. +--cache:: + (With --add) Cache the probes. Any events which successfully added + are also stored in the cache file. + (With --list) Show cached probes. + (With --del) Remove cached probes. + --max-probes=NUM:: Set the maximum number of probe points for an event. Default is 128. @@ -134,19 +143,30 @@ PROBE SYNTAX Probe points are defined by following syntax. 1) Define event based on function name - [EVENT=]FUNC[@SRC][:RLN|+OFFS|%return|;PTN] [ARG ...] + [[GROUP:]EVENT=]FUNC[@SRC][:RLN|+OFFS|%return|;PTN] [ARG ...] 2) Define event based on source file with line number - [EVENT=]SRC:ALN [ARG ...] + [[GROUP:]EVENT=]SRC:ALN [ARG ...] 3) Define event based on source file with lazy pattern - [EVENT=]SRC;PTN [ARG ...] + [[GROUP:]EVENT=]SRC;PTN [ARG ...] + 4) Pre-defined SDT events or cached event with name + %[sdt_PROVIDER:]SDTEVENT + or, + sdt_PROVIDER:SDTEVENT -'EVENT' specifies the name of new event, if omitted, it will be set the name of the probed function. Currently, event group name is set as 'probe'. +'EVENT' specifies the name of new event, if omitted, it will be set the name of the probed function. You can also specify a group name by 'GROUP', if omitted, set 'probe' is used for kprobe and 'probe_<bin>' is used for uprobe. +Note that using existing group name can conflict with other events. Especially, using the group name reserved for kernel modules can hide embedded events in the +modules. 'FUNC' specifies a probed function name, and it may have one of the following options; '+OFFS' is the offset from function entry address in bytes, ':RLN' is the relative-line number from function entry line, and '%return' means that it probes function return. And ';PTN' means lazy matching pattern (see LAZY MATCHING). Note that ';PTN' must be the end of the probe point definition. In addition, '@SRC' specifies a source file which has that function. It is also possible to specify a probe point by the source line number or lazy matching by using 'SRC:ALN' or 'SRC;PTN' syntax, where 'SRC' is the source file path, ':ALN' is the line number and ';PTN' is the lazy matching pattern. 'ARG' specifies the arguments of this probe point, (see PROBE ARGUMENT). +'SDTEVENT' and 'PROVIDER' is the pre-defined event name which is defined by user SDT (Statically Defined Tracing) or the pre-cached probes with event name. +Note that before using the SDT event, the target binary (on which SDT events are defined) must be scanned by linkperf:perf-buildid-cache[1] to make SDT events as cached events. + +For details of the SDT, see below. +https://sourceware.org/gdb/onlinedocs/gdb/Static-Probe-Points.html PROBE ARGUMENT -------------- @@ -226,4 +246,4 @@ Add probes at malloc() function on libc SEE ALSO -------- -linkperf:perf-trace[1], linkperf:perf-record[1] +linkperf:perf-trace[1], linkperf:perf-record[1], linkperf:perf-buildid-cache[1] diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt index 8dbee832abd9..379a2bed07c0 100644 --- a/tools/perf/Documentation/perf-record.txt +++ b/tools/perf/Documentation/perf-record.txt @@ -192,6 +192,9 @@ OPTIONS --period:: Record the sample period. +--sample-cpu:: + Record the sample cpu. + -n:: --no-samples:: Don't sample. @@ -360,6 +363,35 @@ particular perf.data snapshot should be kept or not. Implies --timestamp-filename, --no-buildid and --no-buildid-cache. +--dry-run:: +Parse options then exit. --dry-run can be used to detect errors in cmdline +options. + +'perf record --dry-run -e' can act as a BPF script compiler if llvm.dump-obj +in config file is set to true. + +--tail-synthesize:: +Instead of collecting non-sample events (for example, fork, comm, mmap) at +the beginning of record, collect them during finalizing an output file. +The collected non-sample events reflects the status of the system when +record is finished. + +--overwrite:: +Makes all events use an overwritable ring buffer. An overwritable ring +buffer works like a flight recorder: when it gets full, the kernel will +overwrite the oldest records, that thus will never make it to the +perf.data file. + +When '--overwrite' and '--switch-output' are used perf records and drops +events until it receives a signal, meaning that something unusual was +detected that warrants taking a snapshot of the most current events, +those fitting in the ring buffer at that moment. + +'overwrite' attribute can also be set or canceled for an event using +config terms. For example: 'cycles/overwrite/' and 'instructions/no-overwrite/'. + +Implies --tail-synthesize. + SEE ALSO -------- linkperf:perf-stat[1], linkperf:perf-list[1] diff --git a/tools/perf/Documentation/perf-report.txt b/tools/perf/Documentation/perf-report.txt index 9cbddc290aff..2d1746295abf 100644 --- a/tools/perf/Documentation/perf-report.txt +++ b/tools/perf/Documentation/perf-report.txt @@ -265,6 +265,13 @@ OPTIONS --stdio:: Use the stdio interface. +--stdio-color:: + 'always', 'never' or 'auto', allowing configuring color output + via the command line, in addition to via "color.ui" .perfconfig. + Use '--stdio-color always' to generate color even when redirecting + to a pipe or file. Using just '--stdio-color' is equivalent to + using 'always'. + --tui:: Use the TUI interface, that is integrated with annotate and allows zooming into DSOs or threads, among other features. Use of --tui requires a tty, if one is not present, as when piping to other diff --git a/tools/perf/Documentation/perf-script.txt b/tools/perf/Documentation/perf-script.txt index 4fc44c75263f..1f6c70594f0f 100644 --- a/tools/perf/Documentation/perf-script.txt +++ b/tools/perf/Documentation/perf-script.txt @@ -119,13 +119,13 @@ OPTIONS srcline, period, iregs, brstack, brstacksym, flags. Field list can be prepended with the type, trace, sw or hw, to indicate to which event type the field list applies. - e.g., -f sw:comm,tid,time,ip,sym and -f trace:time,cpu,trace + e.g., -F sw:comm,tid,time,ip,sym and -F trace:time,cpu,trace - perf script -f <fields> + perf script -F <fields> is equivalent to: - perf script -f trace:<fields> -f sw:<fields> -f hw:<fields> + perf script -F trace:<fields> -F sw:<fields> -F hw:<fields> i.e., the specified fields apply to all event types if the type string is not given. @@ -133,9 +133,9 @@ OPTIONS The arguments are processed in the order received. A later usage can reset a prior request. e.g.: - -f trace: -f comm,tid,time,ip,sym + -F trace: -F comm,tid,time,ip,sym - The first -f suppresses trace events (field list is ""), but then the + The first -F suppresses trace events (field list is ""), but then the second invocation sets the fields to comm,tid,time,ip,sym. In this case a warning is given to the user: @@ -143,9 +143,9 @@ OPTIONS Alternatively, consider the order: - -f comm,tid,time,ip,sym -f trace: + -F comm,tid,time,ip,sym -F trace: - The first -f sets the fields for all events and the second -f + The first -F sets the fields for all events and the second -F suppresses trace events. The user is given a warning message about the override, and the result of the above is that only S/W and H/W events are displayed with the given fields. @@ -154,14 +154,14 @@ OPTIONS event type, a message is displayed to the user that the option is ignored for that type. For example: - $ perf script -f comm,tid,trace + $ perf script -F comm,tid,trace 'trace' not valid for hardware events. Ignoring. 'trace' not valid for software events. Ignoring. Alternatively, if the type is given an invalid field is specified it is an error. For example: - perf script -v -f sw:comm,tid,trace + perf script -v -F sw:comm,tid,trace 'trace' not valid for software events. At this point usage is displayed, and perf-script exits. @@ -170,10 +170,19 @@ OPTIONS Trace decoding. The flags are "bcrosyiABEx" which stand for branch, call, return, conditional, system, asynchronous, interrupt, transaction abort, trace begin, trace end, and in transaction, - respectively. + respectively. Known combinations of flags are printed more nicely e.g. + "call" for "bc", "return" for "br", "jcc" for "bo", "jmp" for "b", + "int" for "bci", "iret" for "bri", "syscall" for "bcs", "sysret" for "brs", + "async" for "by", "hw int" for "bcyi", "tx abrt" for "bA", "tr strt" for "bB", + "tr end" for "bE". However the "x" flag will be display separately in those + cases e.g. "jcc (x)" for a condition branch within a transaction. + + The callindent field is synthesized and may have a value when + Instruction Trace decoding. For calls and returns, it will display the + name of the symbol indented with spaces to reflect the stack depth. Finally, a user may not set fields to none for all event types. - i.e., -f "" is not allowed. + i.e., -F "" is not allowed. The brstack output includes branch related information with raw addresses using the /v/v/v/v/ syntax in the following order: diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt index 04f23b404bbc..d96ccd4844df 100644 --- a/tools/perf/Documentation/perf-stat.txt +++ b/tools/perf/Documentation/perf-stat.txt @@ -204,6 +204,38 @@ Aggregate counts per physical processor for system-wide mode measurements. --no-aggr:: Do not aggregate counts across all monitored CPUs. +--topdown:: +Print top down level 1 metrics if supported by the CPU. This allows to +determine bottle necks in the CPU pipeline for CPU bound workloads, +by breaking the cycles consumed down into frontend bound, backend bound, +bad speculation and retiring. + +Frontend bound means that the CPU cannot fetch and decode instructions fast +enough. Backend bound means that computation or memory access is the bottle +neck. Bad Speculation means that the CPU wasted cycles due to branch +mispredictions and similar issues. Retiring means that the CPU computed without +an apparently bottleneck. The bottleneck is only the real bottleneck +if the workload is actually bound by the CPU and not by something else. + +For best results it is usually a good idea to use it with interval +mode like -I 1000, as the bottleneck of workloads can change often. + +The top down metrics are collected per core instead of per +CPU thread. Per core mode is automatically enabled +and -a (global monitoring) is needed, requiring root rights or +perf.perf_event_paranoid=-1. + +Topdown uses the full Performance Monitoring Unit, and needs +disabling of the NMI watchdog (as root): +echo 0 > /proc/sys/kernel/nmi_watchdog +for best results. Otherwise the bottlenecks may be inconsistent +on workload with changing phases. + +This enables --metric-only, unless overriden with --no-metric-only. + +To interpret the results it is usually needed to know on which +CPUs the workload runs on. If needed the CPUs can be forced using +taskset. EXAMPLES -------- diff --git a/tools/perf/Documentation/perf-test.txt b/tools/perf/Documentation/perf-test.txt index 31a5c3ea7f74..b329c65d7f40 100644 --- a/tools/perf/Documentation/perf-test.txt +++ b/tools/perf/Documentation/perf-test.txt @@ -30,3 +30,7 @@ OPTIONS -v:: --verbose:: Be more verbose. + +-F:: +--dont-fork:: + Do not fork child for each test, run all tests within single process. diff --git a/tools/perf/Documentation/perf.data-file-format.txt b/tools/perf/Documentation/perf.data-file-format.txt new file mode 100644 index 000000000000..fdc99fe6bbc3 --- /dev/null +++ b/tools/perf/Documentation/perf.data-file-format.txt @@ -0,0 +1,442 @@ +perf.data format + +Uptodate as of v4.7 + +This document describes the on-disk perf.data format, generated by perf record +or perf inject and consumed by the other perf tools. + +On a high level perf.data contains the events generated by the PMUs, plus metadata. + +All fields are in native-endian of the machine that generated the perf.data. + +When perf is writing to a pipe it uses a special version of the file +format that does not rely on seeking to adjust data offsets. This +format is not described here. The pipe version can be converted to +normal perf.data with perf inject. + +The file starts with a perf_header: + +struct perf_header { + char magic[8]; /* PERFILE2 */ + uint64_t size; /* size of the header */ + uint64_t attr_size; /* size of an attribute in attrs */ + struct perf_file_section attrs; + struct perf_file_section data; + struct perf_file_section event_types; + uint64_t flags; + uint64_t flags1[3]; +}; + +The magic number identifies the perf file and the version. Current perf versions +use PERFILE2. Old perf versions generated a version 1 format (PERFFILE). Version 1 +is not described here. The magic number also identifies the endian. When the +magic value is 64bit byte swapped compared the file is in non-native +endian. + +A perf_file_section contains a pointer to another section of the perf file. +The header contains three such pointers: for attributes, data and event types. + +struct perf_file_section { + uint64_t offset; /* offset from start of file */ + uint64_t size; /* size of the section */ +}; + +Flags section: + +The header is followed by different optional headers, described by the bits set +in flags. Only headers for which the bit is set are included. Each header +consists of a perf_file_section located after the initial header. +The respective perf_file_section points to the data of the additional +header and defines its size. + +Some headers consist of strings, which are defined like this: + +struct perf_header_string { + uint32_t len; + char string[len]; /* zero terminated */ +}; + +Some headers consist of a sequence of strings, which start with a + +struct perf_header_string_list { + uint32_t nr; + struct perf_header_string strings[nr]; /* variable length records */ +}; + +The bits are the flags bits in a 256 bit bitmap starting with +flags. These define the valid bits: + + HEADER_RESERVED = 0, /* always cleared */ + HEADER_FIRST_FEATURE = 1, + HEADER_TRACING_DATA = 1, + +Describe me. + + HEADER_BUILD_ID = 2, + +The header consists of an sequence of build_id_event. The size of each record +is defined by header.size (see perf_event.h). Each event defines a ELF build id +for a executable file name for a pid. An ELF build id is a unique identifier +assigned by the linker to an executable. + +struct build_id_event { + struct perf_event_header header; + pid_t pid; + uint8_t build_id[24]; + char filename[header.size - offsetof(struct build_id_event, filename)]; +}; + + HEADER_HOSTNAME = 3, + +A perf_header_string with the hostname where the data was collected +(uname -n) + + HEADER_OSRELEASE = 4, + +A perf_header_string with the os release where the data was collected +(uname -r) + + HEADER_VERSION = 5, + +A perf_header_string with the perf user tool version where the +data was collected. This is the same as the version of the source tree +the perf tool was built from. + + HEADER_ARCH = 6, + +A perf_header_string with the CPU architecture (uname -m) + + HEADER_NRCPUS = 7, + +A structure defining the number of CPUs. + +struct nr_cpus { + uint32_t nr_cpus_online; + uint32_t nr_cpus_available; /* CPUs not yet onlined */ +}; + + HEADER_CPUDESC = 8, + +A perf_header_string with description of the CPU. On x86 this is the model name +in /proc/cpuinfo + + HEADER_CPUID = 9, + +A perf_header_string with the exact CPU type. On x86 this is +vendor,family,model,stepping. For example: GenuineIntel,6,69,1 + + HEADER_TOTAL_MEM = 10, + +An uint64_t with the total memory in bytes. + + HEADER_CMDLINE = 11, + +A perf_header_string with the perf command line used to collect the data. + + HEADER_EVENT_DESC = 12, + +Another description of the perf_event_attrs, more detailed than header.attrs +including IDs and names. See perf_event.h or the man page for a description +of a struct perf_event_attr. + +struct { + uint32_t nr; /* number of events */ + uint32_t attr_size; /* size of each perf_event_attr */ + struct { + struct perf_event_attr attr; /* size of attr_size */ + uint32_t nr_ids; + struct perf_header_string event_string; + uint64_t ids[nr_ids]; + } events[nr]; /* Variable length records */ +}; + + HEADER_CPU_TOPOLOGY = 13, + +String lists defining the core and CPU threads topology. + +struct { + struct perf_header_string_list cores; /* Variable length */ + struct perf_header_string_list threads; /* Variable length */ +}; + +Example: + sibling cores : 0-3 + sibling threads : 0-1 + sibling threads : 2-3 + + HEADER_NUMA_TOPOLOGY = 14, + + A list of NUMA node descriptions + +struct { + uint32_t nr; + struct { + uint32_t nodenr; + uint64_t mem_total; + uint64_t mem_free; + struct perf_header_string cpus; + } nodes[nr]; /* Variable length records */ +}; + + HEADER_BRANCH_STACK = 15, + +Not implemented in perf. + + HEADER_PMU_MAPPINGS = 16, + + A list of PMU structures, defining the different PMUs supported by perf. + +struct { + uint32_t nr; + struct pmu { + uint32_t pmu_type; + struct perf_header_string pmu_name; + } [nr]; /* Variable length records */ +}; + + HEADER_GROUP_DESC = 17, + + Description of counter groups ({...} in perf syntax) + +struct { + uint32_t nr; + struct { + struct perf_header_string string; + uint32_t leader_idx; + uint32_t nr_members; + } [nr]; /* Variable length records */ +}; + + HEADER_AUXTRACE = 18, + +Define additional auxtrace areas in the perf.data. auxtrace is used to store +undecoded hardware tracing information, such as Intel Processor Trace data. + +/** + * struct auxtrace_index_entry - indexes a AUX area tracing event within a + * perf.data file. + * @file_offset: offset within the perf.data file + * @sz: size of the event + */ +struct auxtrace_index_entry { + u64 file_offset; + u64 sz; +}; + +#define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256 + +/** + * struct auxtrace_index - index of AUX area tracing events within a perf.data + * file. + * @list: linking a number of arrays of entries + * @nr: number of entries + * @entries: array of entries + */ +struct auxtrace_index { + struct list_head list; + size_t nr; + struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT]; +}; + + other bits are reserved and should ignored for now + HEADER_FEAT_BITS = 256, + +Attributes + +This is an array of perf_event_attrs, each attr_size bytes long, which defines +each event collected. See perf_event.h or the man page for a detailed +description. + +Data + +This section is the bulk of the file. It consist of a stream of perf_events +describing events. This matches the format generated by the kernel. +See perf_event.h or the manpage for a detailed description. + +Some notes on parsing: + +Ordering + +The events are not necessarily in time stamp order, as they can be +collected in parallel on different CPUs. If the events should be +processed in time order they need to be sorted first. It is possible +to only do a partial sort using the FINISHED_ROUND event header (see +below). perf record guarantees that there is no reordering over a +FINISHED_ROUND. + +ID vs IDENTIFIER + +When the event stream contains multiple events each event is identified +by an ID. This can be either through the PERF_SAMPLE_ID or the +PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is +at a fixed offset from the event header, which allows reliable +parsing of the header. Relying on ID may be ambigious. +IDENTIFIER is only supported by newer Linux kernels. + +Perf record specific events: + +In addition to the kernel generated event types perf record adds its +own event types (in addition it also synthesizes some kernel events, +for example MMAP events) + + PERF_RECORD_USER_TYPE_START = 64, + PERF_RECORD_HEADER_ATTR = 64, + +struct attr_event { + struct perf_event_header header; + struct perf_event_attr attr; + uint64_t id[]; +}; + + PERF_RECORD_HEADER_EVENT_TYPE = 65, /* depreceated */ + +#define MAX_EVENT_NAME 64 + +struct perf_trace_event_type { + uint64_t event_id; + char name[MAX_EVENT_NAME]; +}; + +struct event_type_event { + struct perf_event_header header; + struct perf_trace_event_type event_type; +}; + + + PERF_RECORD_HEADER_TRACING_DATA = 66, + +Describe me + +struct tracing_data_event { + struct perf_event_header header; + uint32_t size; +}; + + PERF_RECORD_HEADER_BUILD_ID = 67, + +Define a ELF build ID for a referenced executable. + + struct build_id_event; /* See above */ + + PERF_RECORD_FINISHED_ROUND = 68, + +No event reordering over this header. No payload. + + PERF_RECORD_ID_INDEX = 69, + +Map event ids to CPUs and TIDs. + +struct id_index_entry { + uint64_t id; + uint64_t idx; + uint64_t cpu; + uint64_t tid; +}; + +struct id_index_event { + struct perf_event_header header; + uint64_t nr; + struct id_index_entry entries[nr]; +}; + + PERF_RECORD_AUXTRACE_INFO = 70, + +Auxtrace type specific information. Describe me + +struct auxtrace_info_event { + struct perf_event_header header; + uint32_t type; + uint32_t reserved__; /* For alignment */ + uint64_t priv[]; +}; + + PERF_RECORD_AUXTRACE = 71, + +Defines auxtrace data. Followed by the actual data. The contents of +the auxtrace data is dependent on the event and the CPU. For example +for Intel Processor Trace it contains Processor Trace data generated +by the CPU. + +struct auxtrace_event { + struct perf_event_header header; + uint64_t size; + uint64_t offset; + uint64_t reference; + uint32_t idx; + uint32_t tid; + uint32_t cpu; + uint32_t reserved__; /* For alignment */ +}; + +struct aux_event { + struct perf_event_header header; + uint64_t aux_offset; + uint64_t aux_size; + uint64_t flags; +}; + + PERF_RECORD_AUXTRACE_ERROR = 72, + +Describes an error in hardware tracing + +enum auxtrace_error_type { + PERF_AUXTRACE_ERROR_ITRACE = 1, + PERF_AUXTRACE_ERROR_MAX +}; + +#define MAX_AUXTRACE_ERROR_MSG 64 + +struct auxtrace_error_event { + struct perf_event_header header; + uint32_t type; + uint32_t code; + uint32_t cpu; + uint32_t pid; + uint32_t tid; + uint32_t reserved__; /* For alignment */ + uint64_t ip; + char msg[MAX_AUXTRACE_ERROR_MSG]; +}; + +Event types + +Define the event attributes with their IDs. + +An array bound by the perf_file_section size. + + struct { + struct perf_event_attr attr; /* Size defined by header.attr_size */ + struct perf_file_section ids; + } + +ids points to a array of uint64_t defining the ids for event attr attr. + +References: + +include/uapi/linux/perf_event.h + +This is the canonical description of the kernel generated perf_events +and the perf_event_attrs. + +perf_events manpage + +A manpage describing perf_event and perf_event_attr is here: +http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html +This tends to be slightly behind the kernel include, but has better +descriptions. An (typically older) version of the man page may be +included with the standard Linux man pages, available with "man +perf_events" + +pmu-tools + +https://github.com/andikleen/pmu-tools/tree/master/parser + +A definition of the perf.data format in python "construct" format is available +in pmu-tools parser. This allows to read perf.data from python and dump it. + +quipper + +The quipper C++ parser is available at +https://chromium.googlesource.com/chromiumos/platform/chromiumos-wide-profiling/ +Unfortunately this parser tends to be many versions behind and may not be able +to parse data files generated by recent perf. |