linux/tools/perf/Documentation
Roberto Agostino Vitillo b50311dc2a perf report: Add support for taken branch sampling
This patch adds support for taken branch sampling, i.e, the
PERF_SAMPLE_BRANCH_STACK feature to perf report. In other
words, to display histograms based on taken branches rather
than executed instructions addresses.

The new option is called -b and it takes no argument. To
generate meaningful output, the perf.data must have been
obtained using perf record -b xxx ... where xxx is a branch
filter option.

The output shows symbols, modules, sorted by 'who branches
where' the most often. The percentages reported in the first
column refer to the total number of branches captured and
not the usual number of samples.

Here is a quick example.
Here branchy is simple test program which looks as follows:

void f2(void)
{}
void f3(void)
{}
void f1(unsigned long n)
{
  if (n & 1UL)
    f2();
  else
    f3();
}
int main(void)
{
  unsigned long i;

  for (i=0; i < N; i++)
   f1(i);
  return 0;
}

Here is the output captured on Nehalem, if we are
only interested in user level function calls.

$ perf record -b any_call,u -e cycles:u branchy

$ perf report -b --sort=symbol
    52.34%  [.] main                   [.] f1
    24.04%  [.] f1                     [.] f3
    23.60%  [.] f1                     [.] f2
     0.01%  [k] _IO_new_file_xsputn    [k] _IO_file_overflow
     0.01%  [k] _IO_vfprintf_internal  [k] _IO_new_file_xsputn
     0.01%  [k] _IO_vfprintf_internal  [k] strchrnul
     0.01%  [k] __printf               [k] _IO_vfprintf_internal
     0.01%  [k] main                   [k] __printf

About half (52%) of the call branches captured are from main()
-> f1(). The second half (24%+23%) is split in two equal shares
between f1() -> f2(), f1() ->f3(). The output is as expected
given the code.

It should be noted, that using -b in perf record does not
eliminate information in the perf.data file. Consequently, a
typical profile can also be obtained by perf report by simply
not using its -b option.

It is possible to sort on branch related columns:

   - dso_from, symbol_from
   - dso_to, symbol_to
   - mispredict

Signed-off-by: Roberto Agostino Vitillo <ravitillo@lbl.gov>
Signed-off-by: Stephane Eranian <eranian@google.com>
Cc: peterz@infradead.org
Cc: acme@redhat.com
Cc: robert.richter@amd.com
Cc: ming.m.lin@intel.com
Cc: andi@firstfloor.org
Cc: asharma@fb.com
Cc: vweaver1@eecs.utk.edu
Cc: khandual@linux.vnet.ibm.com
Cc: dsahern@gmail.com
Link: http://lkml.kernel.org/r/1328826068-11713-14-git-send-email-eranian@google.com
Signed-off-by: Ingo Molnar <mingo@elte.hu>
2012-03-09 08:26:05 +01:00
..
asciidoc.conf
examples.txt mm-tracepoint: fix documentation and examples 2012-01-10 16:30:41 -08:00
Makefile perf doc: Allow producing documentation in a specified output directory 2012-02-06 19:16:03 -02:00
manpage-1.72.xsl
manpage-base.xsl
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-suppress-sp.xsl
perf-annotate.txt perf report: Accept fifos as input file 2011-12-23 17:01:03 -02:00
perf-archive.txt perf archive: Add documentation 2010-01-20 08:54:58 +01:00
perf-bench.txt perf tools: Fixup minor doc formatting issues 2010-05-05 11:23:27 -03:00
perf-buildid-cache.txt perf man pages: Fix cut'n'paste error 2010-07-28 11:30:10 -03:00
perf-buildid-list.txt perf report: Accept fifos as input file 2011-12-23 17:01:03 -02:00
perf-diff.txt perf symbols: Add symfs option for off-box analysis using specified tree 2010-12-21 20:17:51 -02:00
perf-evlist.txt perf report: Accept fifos as input file 2011-12-23 17:01:03 -02:00
perf-help.txt
perf-inject.txt perf inject: Add missing bits 2010-05-04 10:48:22 -03:00
perf-kmem.txt perf report: Accept fifos as input file 2011-12-23 17:01:03 -02:00
perf-kvm.txt perf kvm: Document missing options 2010-12-01 18:22:46 -02:00
perf-list.txt perf tools: Add support for guest/host-only profiling 2012-01-06 15:49:49 -02:00
perf-lock.txt perf lock: Document lock info subcommand 2012-01-30 18:30:48 -02:00
perf-probe.txt perf probe: Support adding probes on offline kernel modules 2011-07-15 16:25:12 -04:00
perf-record.txt perf record: Add support for sampling taken branch 2012-03-09 08:26:05 +01:00
perf-report.txt perf report: Add support for taken branch sampling 2012-03-09 08:26:05 +01:00
perf-sched.txt perf report: Accept fifos as input file 2011-12-23 17:01:03 -02:00
perf-script-perl.txt sched: Get rid of lock_depth 2011-04-24 13:18:38 +02:00
perf-script-python.txt sched: Get rid of lock_depth 2011-04-24 13:18:38 +02:00
perf-script.txt perf script: Add option resolving vmlinux path 2012-01-30 18:13:07 -02:00
perf-stat.txt perf tools: Allow multiple threads or processes in record, stat, top 2012-02-13 22:54:11 -02:00
perf-test.txt perf test: Allow running just a subset of the available tests 2011-11-29 14:04:35 -02:00
perf-timechart.txt perf report: Accept fifos as input file 2011-12-23 17:01:03 -02:00
perf-top.txt perf tools: Allow multiple threads or processes in record, stat, top 2012-02-13 22:54:11 -02:00
perf.txt perf: Fix few typos + cosmetics 2010-01-13 17:39:44 +01:00
perfconfig.example perf ui browser: Make the colors configurable and change the defaults 2011-10-18 17:03:32 -02:00