Re: [PATCH v11 06/24] perf config: Document variables for 'annotate' section in man page

[Namhyung Kim]

On Tue, Nov 17, 2015 at 10:53:26PM +0900, Taeung Song wrote:
> Explain 'annotate' section and its variables.
> 
> 'hide_src_code', 'use_offset', 'jump_arrows' and 'show_nr_jumps'.

The 'show_linenr' and 'show_total_period' are missing.  Also you'd
better to mention the default values for each option.

And some nitpicks below..

> 
> Cc: Namhyung Kim <namhyung@xxxxxxxxxx>
> Cc: Jiri Olsa <jolsa@xxxxxxxxxx>
> Signed-off-by: Taeung Song <treeze.taeung@xxxxxxxxx>
> ---
>  tools/perf/Documentation/perf-config.txt | 76 ++++++++++++++++++++++++++++++++
>  1 file changed, 76 insertions(+)
> 
> diff --git a/tools/perf/Documentation/perf-config.txt b/tools/perf/Documentation/perf-config.txt
> index b4ee205..bfbeb34 100644
> --- a/tools/perf/Documentation/perf-config.txt
> +++ b/tools/perf/Documentation/perf-config.txt
> @@ -166,6 +166,82 @@ 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
>  
> +annotate.*::
> +	There're options which work with a 'annotate' sub-command.

AFAIK 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.
> +
> +		â      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 a example.

s/a example/an example/


> +		If a base address is 0XFFFFFFFF81624d50 as below,
> +
> +		ffffffff81624d50 <load0>
> +
> +		a address on assembly code has a specific absolute address as below

s/a address/an address/


> +
> +		ffffffff816250b8:â  mov    0x8(%r14),%rdi
> +
> +		but if use_offset is 'true', a address subtracted from a base address is printed.

Ditto.


> +		The 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.
> +
> +		â      â jmp    1333
> +		â        xchg   %ax,%ax
> +		â1330:   mov    %r15,%r10
> +		â1333:   cmp    %r15,%r14
> +
> +        annotate.show_nr_jumps::
> +		Let's see a part of assembly code.
> +
> +		â1382:   movb   $0x1,-0x270(%rbp)
> +
> +		If use this, the number of branches branching to that address can be printed as below.

I think it'd be better to avoid using similar words in a row.
How about "number of branches jumping to that address" instead?

Thanks,
Namhyung


> +
> +		â1 1382:   movb   $0x1,-0x270(%rbp)
> +
>  SEE ALSO
>  --------
>  linkperf:perf[1]
> -- 
> 1.9.1
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/