Re: [PATCH v11 10/24] perf config: Document variables for 'call-graph' section in man page

[Taeung Song <treeze.taeung@gmail.com>]

Hi, Namhyung


> On Nov 18, 2015, at 11:51 AM, Namhyung Kim <namhyung@kernel.org> wrote:
> 
> On Tue, Nov 17, 2015 at 10:53:30PM +0900, Taeung Song wrote:
>> Explain 'call-graph' section and its variables.
>> 
>> 'record-mode', 'dump-size', 'print-type', 'order',
>> 'sort-key', 'threshold' and 'print-limit'.
>> 
>> Cc: Namhyung Kim <namhyung@kernel.org>
>> Cc: Jiri Olsa <jolsa@redhat.com>
>> Signed-off-by: Taeung Song <treeze.taeung@gmail.com>
>> ---
>> tools/perf/Documentation/perf-config.txt | 65 ++++++++++++++++++++++++++++++++
>> 1 file changed, 65 insertions(+)
>> 
>> diff --git a/tools/perf/Documentation/perf-config.txt b/tools/perf/Documentation/perf-config.txt
>> index 7d386d4..dc659d6 100644
>> --- a/tools/perf/Documentation/perf-config.txt
>> +++ b/tools/perf/Documentation/perf-config.txt
>> @@ -285,6 +285,71 @@ ui.*::
>> 		There're columns as header 'Overhead', 'Children', 'Shared Object', 'Symbol', 'self'.
>> 		If this option is false, they are hiden. This option is only applied to TUI.
>> 
>> +call-graph.*::
>> +	When sub-commands 'top' and 'report' work with -g/—-children
>> +	there're options in control of call-graph.
>> +
>> +	call-graph.record-mode::
>> +		The record-mode can be 'fp' (frame pointer) and 'dwarf'.
> 
> Also 'lbr' can be used, but it only work for recent intel cpus.
> 
> 
>> +		The value of 'dwarf' is effective only if perf detect needed library
>> +		(libunwind or a recent version of libdw).  Also it doesn't *require*
>> +		the dump-size option since it can use the default value of 8192 if
>> +		missing.
> 
> I think the last sentence can be omitted.
> 
> 
>> +
>> +	call-graph.dump-size::
>> +		The size of stack to dump in order to do post-unwinding. Default is 8192 (byte).
>> +		When using dwarf into record-mode this option should have a value.
> 
> This contradicts the above, it'll use the default size if omitted.
> 
> 
>> +
>> +	call-graph.print-type::
>> +		The print-types can be graph (graph absolute), fractal (graph relative), flat.
>> +		This option controls a way to show overhead for each callchain entry.
>> +		Suppose a following example.
>> +
>> +		Overhead  Symbols
>> +		........  .......
>> +		  40.00%  foo
>> +		      |
>> +		      --- foo
>> +		      |
>> +		      |--50.00%-- bar
>> +		      |           main
>> +		      |
>> +		      --50.00%-- baz
>> +		                 main
> 
>                      ^
> 		      it needs one more whitespace
> 

I checked this patch file and whitespace and tab characters on it.
But I think the lacking whitespace  because of mail client.
After 'make install’ I checked it but there is no lack of whitespace.
Are there different problems that I missed ?


Thanks,
Taeung

> 
>> +
>> +		This output is a 'fractal' format. The 'foo' came from 'bar' and 'baz' exactly
>> +		half and half so 'fractal' shows 50.00% for each
>> +		(meaning that it assumes 100% total overhead of 'foo').
>> +
>> +		The 'graph' uses absolute overhead value of 'foo' as total so each of
>> +		'bar' and 'baz' callchain will have 20.00% of overhead.
>> +
>> +	call-graph.order::
>> +		This option controls print order of callchains. The default is
>> +		'callee' which means callee is printed at top and then followed by its
>> +		caller and so on. The 'caller' prints it in reverse order.
>> +
>> +		If this option is not set and report.children or top.children is
>> +		set to true (or the equivalent command line option is given),
>> +		the default value of this option is changed to 'caller' for the
>> +		execution of 'perf report' or 'perf top'. Other commands will
>> +		still default to 'callee'.
>> +
>> +	call-graph.sort-key::
>> +		The callchains are merged if they contain same information.
>> +		The sort-key option determines a way to compare the callchains.
>> +		A value of 'sort-key' can be 'function' or 'address'.
>> +		The default is 'function'.
>> +
>> +	call-graph.threshold::
>> +		When there're many callchains it'd print tons of lines.  So perf omits
>> +		small callchains under a certain overhead (threshold) and this option
>> +		control the threashold. Default is 0.5 (%).
> 
> s/threashold/threshold/
> 
> Also it'd be better to mention that the overhead is calculated by
> value depends on call-graph.print-type.
> 
> 
>> +
>> +	call-graph.print-limit::
>> +		This is another way to control the number of callchains printed for a
>> +		single entry. Default is 0 which means no limitation.
> 
> This is a maximum number of lines of callchain printed for a single
> histogram entry.
> 
> Thanks,
> Namhyung
> 
> 
>> +
>> SEE ALSO
>> --------
>> linkperf:perf[1]
>> -- 
>> 1.9.1