perf config: Document variables for 'annotate' section in man page

Explain 'annotate' section and its variables.

'hide_src_code', 'use_offset', 'jump_arrows',
'show_linenr', 'show_nr_jump' and 'show_total_period'.

Signed-off-by: Taeung Song <treeze.taeung@gmail.com>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Namhyung Kim <namhyung@kernel.org>
Link: http://lkml.kernel.org/r/1452253193-30502-5-git-send-email-treeze.taeung@gmail.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>

diff --git a/tools/perf/Documentation/perf-config.txt b/tools/perf/Documentation/perf-config.txt
index a095f0c..cb7ca50 100644 (file)
--- a/tools/perf/Documentation/perf-config.txt
+++ b/tools/perf/Documentation/perf-config.txt
@@ -169,6 +169,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
 
+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]