linux/tools/perf/Documentation
Naohiro Aota 19f00b0117 perf probe: Support signedness casting
The 'perf probe' tool detects a variable's type and use the detected
type to add a new probe. Then, kprobes prints its variable in
hexadecimal format if the variable is unsigned and prints in decimal if
it is signed.

We sometimes want to see unsigned variable in decimal format (i.e.
sector_t or size_t). In that case, we need to investigate the variable's
size manually to specify just signedness.

This patch add signedness casting support. By specifying "s" or "u" as a
type, perf-probe will investigate variable size as usual and use the
specified signedness.

E.g. without this:

  $ perf probe -a 'submit_bio bio->bi_iter.bi_sector'
  Added new event:
    probe:submit_bio     (on submit_bio with bi_sector=bio->bi_iter.bi_sector)
  You can now use it in all perf tools, such as:
          perf record -e probe:submit_bio -aR sleep 1
  $ cat trace_pipe|head
          dbench-9692  [003] d..1   971.096633: submit_bio: (submit_bio+0x0/0x140) bi_sector=0x3a3d00
          dbench-9692  [003] d..1   971.096685: submit_bio: (submit_bio+0x0/0x140) bi_sector=0x1a3d80
          dbench-9692  [003] d..1   971.096687: submit_bio: (submit_bio+0x0/0x140) bi_sector=0x3a3d80
...
  // need to investigate the variable size
  $ perf probe -a 'submit_bio bio->bi_iter.bi_sector:s64'
  Added new event:
    probe:submit_bio     (on submit_bio with bi_sector=bio->bi_iter.bi_sector:s64)
  You can now use it in all perf tools, such as:
        perf record -e probe:submit_bio -aR sleep 1

  With this:

  // just use "s" to cast its signedness
  $ perf probe -v -a 'submit_bio bio->bi_iter.bi_sector:s'
  Added new event:
    probe:submit_bio     (on submit_bio with bi_sector=bio->bi_iter.bi_sector:s)
  You can now use it in all perf tools, such as:
          perf record -e probe:submit_bio -aR sleep 1
  $ cat trace_pipe|head
          dbench-9689  [001] d..1  1212.391237: submit_bio: (submit_bio+0x0/0x140) bi_sector=128
          dbench-9689  [001] d..1  1212.391252: submit_bio: (submit_bio+0x0/0x140) bi_sector=131072
          dbench-9697  [006] d..1  1212.398611: submit_bio: (submit_bio+0x0/0x140) bi_sector=30208

  This commit also update perf-probe.txt to describe "types". Most parts
  are based on existing documentation: Documentation/trace/kprobetrace.txt

Committer note:

Testing using 'perf trace':

  # perf probe -a 'submit_bio bio->bi_iter.bi_sector'
  Added new event:
    probe:submit_bio     (on submit_bio with bi_sector=bio->bi_iter.bi_sector)

  You can now use it in all perf tools, such as:

	perf record -e probe:submit_bio -aR sleep 1

  # trace --no-syscalls --ev probe:submit_bio
      0.000 probe:submit_bio:(ffffffffac3aee00) bi_sector=0xc133c0)
   3181.861 probe:submit_bio:(ffffffffac3aee00) bi_sector=0x6cffb8)
   3181.881 probe:submit_bio:(ffffffffac3aee00) bi_sector=0x6cffc0)
   3184.488 probe:submit_bio:(ffffffffac3aee00) bi_sector=0x6cffc8)
<SNIP>
   4717.927 probe:submit_bio:(ffffffffac3aee00) bi_sector=0x4dc7a88)
   4717.970 probe:submit_bio:(ffffffffac3aee00) bi_sector=0x4dc7880)
  ^C[root@jouet ~]#

Now, using this new feature:

[root@jouet ~]# perf probe -a 'submit_bio bio->bi_iter.bi_sector:s'
Added new event:
  probe:submit_bio     (on submit_bio with bi_sector=bio->bi_iter.bi_sector:s)

You can now use it in all perf tools, such as:

	perf record -e probe:submit_bio -aR sleep 1

  [root@jouet ~]# trace --no-syscalls --ev probe:submit_bio
     0.000 probe:submit_bio:(ffffffffac3aee00) bi_sector=7145704)
     0.017 probe:submit_bio:(ffffffffac3aee00) bi_sector=7145712)
     0.019 probe:submit_bio:(ffffffffac3aee00) bi_sector=7145720)
     2.567 probe:submit_bio:(ffffffffac3aee00) bi_sector=7145728)
  5631.919 probe:submit_bio:(ffffffffac3aee00) bi_sector=0)
  5631.941 probe:submit_bio:(ffffffffac3aee00) bi_sector=8)
  5631.945 probe:submit_bio:(ffffffffac3aee00) bi_sector=16)
  5631.948 probe:submit_bio:(ffffffffac3aee00) bi_sector=24)
  ^C#

With callchains:

  # trace --no-syscalls --ev probe:submit_bio/max-stack=10/
     0.000 probe:submit_bio:(ffffffffac3aee00) bi_sector=50662544)
                                       submit_bio+0xa8200001 ([kernel.kallsyms])
                                       submit_bh+0xa8200013 ([kernel.kallsyms])
                                       jbd2_journal_commit_transaction+0xa8200691 ([kernel.kallsyms])
                                       kjournald2+0xa82000ca ([kernel.kallsyms])
                                       kthread+0xa82000d8 ([kernel.kallsyms])
                                       ret_from_fork+0xa820001f ([kernel.kallsyms])
     0.023 probe:submit_bio:(ffffffffac3aee00) bi_sector=50662552)
                                       submit_bio+0xa8200001 ([kernel.kallsyms])
                                       submit_bh+0xa8200013 ([kernel.kallsyms])
                                       jbd2_journal_commit_transaction+0xa8200691 ([kernel.kallsyms])
                                       kjournald2+0xa82000ca ([kernel.kallsyms])
                                       kthread+0xa82000d8 ([kernel.kallsyms])
                                       ret_from_fork+0xa820001f ([kernel.kallsyms])
     0.027 probe:submit_bio:(ffffffffac3aee00) bi_sector=50662560)
                                       submit_bio+0xa8200001 ([kernel.kallsyms])
                                       submit_bh+0xa8200013 ([kernel.kallsyms])
                                       jbd2_journal_commit_transaction+0xa8200691 ([kernel.kallsyms])
                                       kjournald2+0xa82000ca ([kernel.kallsyms])
                                       kthread+0xa82000d8 ([kernel.kallsyms])
                                       ret_from_fork+0xa820001f ([kernel.kallsyms])
     2.593 probe:submit_bio:(ffffffffac3aee00) bi_sector=50662568)
                                       submit_bio+0xa8200001 ([kernel.kallsyms])
                                       submit_bh+0xa8200013 ([kernel.kallsyms])
                                       journal_submit_commit_record+0xa82001ac ([kernel.kallsyms])
                                       jbd2_journal_commit_transaction+0xa82012e8 ([kernel.kallsyms])
                                       kjournald2+0xa82000ca ([kernel.kallsyms])
                                       kthread+0xa82000d8 ([kernel.kallsyms])
                                       ret_from_fork+0xa820001f ([kernel.kallsyms])
  ^C#

Signed-off-by: Naohiro Aota <naohiro.aota@hgst.com>
Tested-by: Arnaldo Carvalho de Melo <acme@redhat.com>
Cc: Alexander Shishkin <alexander.shishkin@linux.intel.com>
Cc: Hemant Kumar <hemant@linux.vnet.ibm.com>
Cc: Masami Hiramatsu <mhiramat@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Wang Nan <wangnan0@huawei.com>
Link: http://lkml.kernel.org/r/1470710408-23515-1-git-send-email-naohiro.aota@hgst.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2016-08-09 10:52:22 -03:00
..
android.txt perf tools: Update android build documentation 2016-07-04 20:27:27 -03:00
asciidoc.conf
Build.txt perf build: Add build documentation 2015-02-12 17:53:00 -03:00
callchain-overhead-calculation.txt perf tools: Document --children option in more detail 2015-04-29 10:38:06 -03:00
examples.txt perf record: Remove -f/--force option 2013-07-08 17:37:25 -03:00
intel-bts.txt perf tools: Add Intel BTS support 2015-08-21 11:34:10 -03:00
intel-pt.txt perf tools: Add support for skipping itrace instructions 2016-03-30 11:14:09 -03:00
itrace.txt perf tools: Add support for skipping itrace instructions 2016-03-30 11:14:09 -03:00
jit-interface.txt perf symbols: Add description of JIT interface 2012-08-13 14:55:02 -03:00
Makefile tools: Move utilities.mak from perf to tools/scripts/ 2016-03-18 13:57:20 -03:00
manpage-1.72.xsl
manpage-base.xsl
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-suppress-sp.xsl
perf-annotate.txt perf annotate: Introduce --stdio-color to setup the color output mode selection 2016-07-12 00:00:39 -03:00
perf-archive.txt perf archive: Remove duplicated 'runs' in man page 2013-12-09 15:21:45 -03:00
perf-bench.txt perf bench mem: Rename 'routine' to 'function' 2015-10-19 16:10:25 -03:00
perf-buildid-cache.txt perf buildid-cache: Scan and import user SDT events to probe cache 2016-07-04 19:39:00 -03:00
perf-buildid-list.txt perf report: Accept fifos as input file 2011-12-23 17:01:03 -02:00
perf-config.txt perf config: Add '--system' and '--user' options to select which config file is used 2016-02-12 10:54:46 -03:00
perf-data.txt perf data ctf: Add '--all' option for 'perf data convert' 2016-06-28 10:54:57 -03:00
perf-diff.txt perf tools: Make -f/--force option documentation consistent across tools 2016-03-30 11:14:08 -03:00
perf-evlist.txt perf evlist: Add --trace-fields option to show trace fields 2016-01-08 14:23:02 -03:00
perf-help.txt
perf-inject.txt perf inject: Add jitdump mmap injection support 2016-02-05 09:46:45 -03:00
perf-kmem.txt perf kmem: Add --live option for current allocation stat 2015-05-04 13:34:47 -03:00
perf-kvm.txt perf tools: Configurable per thread proc map processing time out 2015-06-19 18:27:13 -03:00
perf-list.txt perf list: Document event specifications better 2016-04-06 11:19:18 -03:00
perf-lock.txt perf lock: Account for lock average wait time 2013-10-09 11:24:01 -03:00
perf-mem.txt perf mem: Add --ldlat option 2016-06-15 10:35:27 -03:00
perf-probe.txt perf probe: Support signedness casting 2016-08-09 10:52:22 -03:00
perf-record.txt perf record: Add --sample-cpu option 2016-08-02 16:33:29 -03:00
perf-report.txt perf report: Introduce --stdio-color to setup the color output mode selection 2016-07-12 00:00:39 -03:00
perf-sched.txt perf sched map: Display only given cpus 2016-04-13 10:11:52 -03:00
perf-script-perl.txt perf Documentation: Fix typos in perf/Documentation 2014-10-15 17:39:02 -03:00
perf-script-python.txt perf Documentation: Fix typos in perf/Documentation 2014-10-15 17:39:02 -03:00
perf-script.txt perf script: Add 'bpf-output' field to usage message 2016-08-09 10:46:43 -03:00
perf-stat.txt perf stat: Basic support for TopDown in perf stat 2016-06-06 17:04:15 -03:00
perf-test.txt perf test: Add -F/--dont-fork option 2016-06-30 18:27:45 -03:00
perf-timechart.txt perf timechart: Add more options to IO mode 2014-07-10 00:22:54 +02:00
perf-top.txt perf tools: Set the maximum allowed stack from /proc/sys/kernel/perf_event_max_stack 2016-04-27 10:29:07 -03:00
perf-trace.txt perf tools: Fix usage of max_stack sysctl 2016-05-20 11:43:56 -03:00
perf.data-file-format.txt perf tools: Add documentation for perf.data on disk format 2016-06-29 10:07:23 -03:00
perf.txt perf tools: Handle -h and -v options 2015-10-05 16:36:18 -03:00
perfconfig.example perf annotate: Rename 'colors.code' to 'colors.jump_arrows' 2016-01-26 11:52:46 -03:00
tips.txt perf report: Add --hierarchy option 2016-02-24 20:21:15 -03:00