perf tools: Improve call graph documents and help messages

The --call-graph option is complex so we should provide better guide for
users.  Also change help message to be consistent with config option
names.  Now perf top will show help like below:

  $ perf top --call-graph
    Error: option `call-graph' requires a value

   Usage: perf top [<options>]

      --call-graph <record_mode[,record_size],print_type,threshold[,print_limit],order,sort_key[,branch]>
           setup and enables call-graph (stack chain/backtrace):

		record_mode:	call graph recording mode (fp|dwarf|lbr)
		record_size:	if record_mode is 'dwarf', max size of stack recording (<bytes>)
				default: 8192 (bytes)
		print_type:	call graph printing style (graph|flat|fractal|none)
		threshold:	minimum call graph inclusion threshold (<percent>)
		print_limit:	maximum number of call graph entry (<number>)
		order:		call graph order (caller|callee)
		sort_key:	call graph sort key (function|address)
		branch:		include last branch info to call graph (branch)

		Default: fp,graph,0.5,caller,function

Requested-by: Ingo Molnar <mingo@kernel.org>
Signed-off-by: Namhyung Kim <namhyung@kernel.org>
Acked-by: Frederic Weisbecker <fweisbec@gmail.com>
Cc: Adrian Hunter <adrian.hunter@intel.com>
Cc: Borislav Petkov <bp@suse.de>
Cc: Brendan Gregg <brendan.d.gregg@gmail.com>
Cc: Chandler Carruth <chandlerc@gmail.com>
Cc: David Ahern <dsahern@gmail.com>
Cc: Jiri Olsa <jolsa@redhat.com>
Cc: Peter Zijlstra <a.p.zijlstra@chello.nl>
Cc: Stephane Eranian <eranian@google.com>
Cc: Wang Nan <wangnan0@huawei.com>
Link: http://lkml.kernel.org/r/1445524112-5201-2-git-send-email-namhyung@kernel.org
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
This commit is contained in:
Namhyung Kim 2015-10-22 23:28:32 +09:00 committed by Arnaldo Carvalho de Melo
parent 792aeafa8e
commit 76a26549eb
6 changed files with 62 additions and 30 deletions

View file

@ -144,7 +144,7 @@ OPTIONS
--call-graph::
Setup and enable call-graph (stack chain/backtrace) recording,
implies -g.
implies -g. Default is "fp".
Allows specifying "fp" (frame pointer) or "dwarf"
(DWARF's CFI - Call Frame Information) or "lbr"
@ -154,13 +154,18 @@ OPTIONS
In some systems, where binaries are build with gcc
--fomit-frame-pointer, using the "fp" method will produce bogus
call graphs, using "dwarf", if available (perf tools linked to
the libunwind library) should be used instead.
the libunwind or libdw library) should be used instead.
Using the "lbr" method doesn't require any compiler options. It
will produce call graphs from the hardware LBR registers. The
main limition is that it is only available on new Intel
platforms, such as Haswell. It can only get user call chain. It
doesn't work with branch stack sampling at the same time.
When "dwarf" recording is used, perf also records (user) stack dump
when sampled. Default size of the stack dump is 8192 (bytes).
User can change the size by passing the size after comma like
"--call-graph dwarf,4096".
-q::
--quiet::
Don't print any message, useful for scripting.

View file

@ -169,30 +169,40 @@ OPTIONS
--dump-raw-trace::
Dump raw trace in ASCII.
-g [type,min[,limit],order[,key][,branch]]::
--call-graph::
Display call chains using type, min percent threshold, optional print
limit and order.
type can be either:
-g::
--call-graph=<print_type,threshold[,print_limit],order,sort_key,branch>::
Display call chains using type, min percent threshold, print limit,
call order, sort key and branch. Note that ordering of parameters is not
fixed so any parement can be given in an arbitraty order. One exception
is the print_limit which should be preceded by threshold.
print_type can be either:
- flat: single column, linear exposure of call chains.
- graph: use a graph tree, displaying absolute overhead rates.
- graph: use a graph tree, displaying absolute overhead rates. (default)
- fractal: like graph, but displays relative rates. Each branch of
the tree is considered as a new profiled object. +
the tree is considered as a new profiled object.
- none: disable call chain display.
threshold is a percentage value which specifies a minimum percent to be
included in the output call graph. Default is 0.5 (%).
print_limit is only applied when stdio interface is used. It's to limit
number of call graph entries in a single hist entry. Note that it needs
to be given after threshold (but not necessarily consecutive).
Default is 0 (unlimited).
order can be either:
- callee: callee based call graph.
- caller: inverted caller based call graph.
Default is 'caller' when --children is used, otherwise 'callee'.
key can be:
- function: compare on functions
sort_key can be:
- function: compare on functions (default)
- address: compare on individual code addresses
branch can be:
- branch: include last branch information in callgraph
when available. Usually more convenient to use --branch-history
for this.
Default: graph,0.5,caller
- branch: include last branch information in callgraph when available.
Usually more convenient to use --branch-history for this.
--children::
Accumulate callchain of children to parent entry so that then can

View file

@ -1010,7 +1010,8 @@ static struct record record = {
},
};
const char record_callchain_help[] = CALLCHAIN_RECORD_HELP;
const char record_callchain_help[] = CALLCHAIN_RECORD_HELP
"\n\t\t\t\tDefault: fp";
/*
* XXX Will stay a global variable till we fix builtin-script.c to stop messing
@ -1058,7 +1059,7 @@ struct option __record_options[] = {
NULL, "enables call-graph recording" ,
&record_callchain_opt),
OPT_CALLBACK(0, "call-graph", &record.opts,
"mode[,dump_size]", record_callchain_help,
"record_mode[,record_size]", record_callchain_help,
&record_parse_callchain_opt),
OPT_INCR('v', "verbose", &verbose,
"be more verbose (show counter open errors, etc)"),

View file

@ -625,8 +625,11 @@ parse_percent_limit(const struct option *opt, const char *str,
return 0;
}
const char report_callchain_help[] = "Display callchains using " CALLCHAIN_REPORT_HELP ". "
"Default: graph,0.5,caller";
#define CALLCHAIN_DEFAULT_OPT "graph,0.5,caller,function"
const char report_callchain_help[] = "Display call graph (stack chain/backtrace):\n\n"
CALLCHAIN_REPORT_HELP
"\n\t\t\t\tDefault: " CALLCHAIN_DEFAULT_OPT;
int cmd_report(int argc, const char **argv, const char *prefix __maybe_unused)
{
@ -636,7 +639,7 @@ int cmd_report(int argc, const char **argv, const char *prefix __maybe_unused)
bool has_br_stack = false;
int branch_mode = -1;
bool branch_call_mode = false;
char callchain_default_opt[] = "graph,0.5,caller";
char callchain_default_opt[] = CALLCHAIN_DEFAULT_OPT;
const char * const report_usage[] = {
"perf report [<options>]",
NULL
@ -703,7 +706,7 @@ int cmd_report(int argc, const char **argv, const char *prefix __maybe_unused)
OPT_BOOLEAN('x', "exclude-other", &symbol_conf.exclude_other,
"Only display entries with parent-match"),
OPT_CALLBACK_DEFAULT('g', "call-graph", &report,
"output_type,min_percent[,print_limit],call_order[,branch]",
"print_type,threshold[,print_limit],order,sort_key[,branch]",
report_callchain_help, &report_parse_callchain_opt,
callchain_default_opt),
OPT_BOOLEAN(0, "children", &symbol_conf.cumulate_callchain,

View file

@ -1093,7 +1093,8 @@ parse_percent_limit(const struct option *opt, const char *arg,
return 0;
}
const char top_callchain_help[] = CALLCHAIN_RECORD_HELP ", " CALLCHAIN_REPORT_HELP;
const char top_callchain_help[] = CALLCHAIN_RECORD_HELP CALLCHAIN_REPORT_HELP
"\n\t\t\t\tDefault: fp,graph,0.5,caller,function";
int cmd_top(int argc, const char **argv, const char *prefix __maybe_unused)
{
@ -1173,7 +1174,7 @@ int cmd_top(int argc, const char **argv, const char *prefix __maybe_unused)
NULL, "enables call-graph recording and display",
&callchain_opt),
OPT_CALLBACK(0, "call-graph", &top.record_opts,
"mode[,dump_size],output_type,min_percent[,print_limit],call_order[,branch]",
"record_mode[,record_size],print_type,threshold[,print_limit],order,sort_key[,branch]",
top_callchain_help, &parse_callchain_opt),
OPT_BOOLEAN(0, "children", &symbol_conf.cumulate_callchain,
"Accumulate callchains of children and show total overhead as well"),

View file

@ -7,17 +7,29 @@
#include "event.h"
#include "symbol.h"
#define CALLCHAIN_HELP "setup and enables call-graph (stack chain/backtrace) recording: "
#define HELP_PAD "\t\t\t\t"
#define CALLCHAIN_HELP "setup and enables call-graph (stack chain/backtrace):\n\n"
#ifdef HAVE_DWARF_UNWIND_SUPPORT
#define CALLCHAIN_RECORD_HELP CALLCHAIN_HELP "fp dwarf lbr"
# define RECORD_MODE_HELP HELP_PAD "record_mode:\tcall graph recording mode (fp|dwarf|lbr)\n"
#else
#define CALLCHAIN_RECORD_HELP CALLCHAIN_HELP "fp lbr"
# define RECORD_MODE_HELP HELP_PAD "record_mode:\tcall graph recording mode (fp|lbr)\n"
#endif
#define CALLCHAIN_REPORT_HELP "output_type (graph, flat, fractal, or none), " \
"min percent threshold, optional print limit, callchain order, " \
"key (function or address), add branches"
#define RECORD_SIZE_HELP \
HELP_PAD "record_size:\tif record_mode is 'dwarf', max size of stack recording (<bytes>)\n" \
HELP_PAD "\t\tdefault: 8192 (bytes)\n"
#define CALLCHAIN_RECORD_HELP CALLCHAIN_HELP RECORD_MODE_HELP RECORD_SIZE_HELP
#define CALLCHAIN_REPORT_HELP \
HELP_PAD "print_type:\tcall graph printing style (graph|flat|fractal|none)\n" \
HELP_PAD "threshold:\tminimum call graph inclusion threshold (<percent>)\n" \
HELP_PAD "print_limit:\tmaximum number of call graph entry (<number>)\n" \
HELP_PAD "order:\t\tcall graph order (caller|callee)\n" \
HELP_PAD "sort_key:\tcall graph sort key (function|address)\n" \
HELP_PAD "branch:\t\tinclude last branch info to call graph (branch)\n"
enum perf_call_graph_mode {
CALLCHAIN_NONE,