Re: [PATCH v13 04/23] perf config: Document variables for 'annotate' section in man page

[Arnaldo Carvalho de Melo <acme@kernel.org>]

Em Fri, Jan 08, 2016 at 08:39:34PM +0900, Taeung Song escreveu:
> Explain 'annotate' section and its variables.
> 
> 'hide_src_code', 'use_offset', 'jump_arrows',
> 'show_linenr', 'show_nr_jump' and 'show_total_period'.
> 
> Cc: Namhyung Kim <namhyung@kernel.org>
> Cc: Jiri Olsa <jolsa@kernel.org>
> Signed-off-by: Taeung Song <treeze.taeung@gmail.com>
> ---
>  tools/perf/Documentation/perf-config.txt | 110 +++++++++++++++++++++++++++++++
>  1 file changed, 110 insertions(+)
> 
> diff --git a/tools/perf/Documentation/perf-config.txt b/tools/perf/Documentation/perf-config.txt
> index 8835215..85b811f 100644
> --- a/tools/perf/Documentation/perf-config.txt
> +++ b/tools/perf/Documentation/perf-config.txt
> @@ -168,6 +168,116 @@ buildid.*::
>  		cache location, or to disable it altogether. If you want to disable it,
>  		set buildid.dir to /dev/null. The default is $HOME/.debug

I suggest you document here also the hotkeys that are available in the
TUI to toggle those knobs, i.e. please go to the annotate browser and
press 'h', you'll get the list of hotkeys, this way, for someone reading
the man page the information will know that this can be done
interactively, not just by changing a config file.

Also it would be interesting to change the annotate/top/report man page
to point to this documentation.

But this can be done on top, I'm doing quick text flowing/grammar fixes
and applying as much as I can from this patchkit, thanks for continuing
work on it.

- Arnaldo
  
> +annotate.*::
> +	These options work only for TUI.
> +	These are in control of addresses, jump function, source code
> +	in lines of assembly code from a specific program.
> +
> +	annotate.hide_src_code::
> +		If a program which is analyzed has source code,
> +		this option lets 'annotate' print a list of assembly code with the source code.
> +		For example, let's see a part of a program. There're four lines.
> +		If this option is 'true', they can be printed
> +		without source code from a program as below.
> +
> +		│        push   %rbp
> +		│        mov    %rsp,%rbp
> +		│        sub    $0x10,%rsp
> +		│        mov    (%rdi),%rdx
> +
> +		But if this option is 'false', source code of the part
> +		can be also printed as below. Default is 'false'.
> +
> +		│      struct rb_node *rb_next(const struct rb_node *node)
> +		│      {
> +		│        push   %rbp
> +		│        mov    %rsp,%rbp
> +		│        sub    $0x10,%rsp
> +		│              struct rb_node *parent;
> +		│
> +		│              if (RB_EMPTY_NODE(node))
> +		│        mov    (%rdi),%rdx
> +		│              return n;
> +
> +        annotate.use_offset::
> +		Basing on a first address of a loaded function, offset can be used.
> +		Instead of using original addresses of assembly code,
> +		addresses subtracted from a base address can be printed.
> +		Let's illustrate an example.
> +		If a base address is 0XFFFFFFFF81624d50 as below,
> +
> +		ffffffff81624d50 <load0>
> +
> +		an address on assembly code has a specific absolute address as below
> +
> +		ffffffff816250b8:│  mov    0x8(%r14),%rdi
> +
> +		but if use_offset is 'true', an address subtracted from a base address is printed.
> +		Default is true. This option is only applied to TUI.
> +
> +		             368:│  mov    0x8(%r14),%rdi
> +
> +	annotate.jump_arrows::
> +		There can be jump instruction among assembly code.
> +		Depending on a boolean value of jump_arrows,
> +		arrows can be printed or not which represent
> +		where do the instruction jump into as below.
> +
> +		│     ┌──jmp    1333
> +		│     │  xchg   %ax,%ax
> +		│1330:│  mov    %r15,%r10
> +		│1333:└─→cmp    %r15,%r14
> +
> +		If jump_arrow is 'false', the arrows isn't printed as below.
> +		Default is 'false'.
> +
> +		│      ↓ jmp    1333
> +		│        xchg   %ax,%ax
> +		│1330:   mov    %r15,%r10
> +		│1333:   cmp    %r15,%r14
> +
> +        annotate.show_linenr::
> +		When showing source code if this option is 'true',
> +		line numbers are printed as below.
> +
> +		│1628         if (type & PERF_SAMPLE_IDENTIFIER) {
> +		│     ↓ jne    508
> +		│1628                 data->id = *array;
> +		│1629                 array++;
> +		│1630         }
> +
> +		However if this option is 'false', they aren't printed as below.
> +		Default is 'false'.
> +
> +		│             if (type & PERF_SAMPLE_IDENTIFIER) {
> +		│     ↓ jne    508
> +		│                     data->id = *array;
> +		│                     array++;
> +		│             }
> +
> +        annotate.show_nr_jumps::
> +		Let's see a part of assembly code.
> +
> +		│1382:   movb   $0x1,-0x270(%rbp)
> +
> +		If use this, the number of branches jumping to that address can be printed as below.
> +		Default is 'false'.
> +
> +		│1 1382:   movb   $0x1,-0x270(%rbp)
> +
> +        annotate.show_total_period::
> +		To compare two records on an instruction base, with this option
> +		provided, display total number of samples that belong to a line
> +		in assembly code. If this option is 'true', total periods are printed
> +		instead of percent values as below.
> +
> +		  302 │      mov    %eax,%eax
> +
> +		But if this option is 'false', percent values for overhead are printed i.e.
> +		Default is 'false'.
> +
> +		99.93 │      mov    %eax,%eax
> +
>  SEE ALSO
>  --------
>  linkperf:perf[1]
> -- 
> 2.5.0