linux/tools/perf/Documentation
Jin Yao 61d9fc4449 perf script: Support filtering by hex address
'perf script' supports '-S' or '--symbol' options to only list the
records for these symbols. A symbol is typically a name or hex address.
If it's hex address, it is the start address of one symbol.

While it would be useful if we can filter trace records by any hex
address (not only the start address of symbol). So now we support
filtering trace records by more conditions, such as:

- symbol name
- start address of symbol
- any hexadecimal address
- address range

The comparison order is defined as:

1. symbol name comparison
2. symbol start address comparison.
3. any hexadecimal address comparison.
4. address range comparison.

The idea is if we can get a valid address from -S list, we add the
address to addr_list for address comparison otherwise we still leave
it to sym_list for symbol comparison.

Some examples:

  root@kbl-ppc:~# ./perf script -S ffffffff9a477308
            perf  8562 [000] 347303.578858:          1   cycles:  ffffffff9a477308 native_write_msr+0x8 ([kernel.kallsyms])
            perf  8562 [000] 347303.578860:          1   cycles:  ffffffff9a477308 native_write_msr+0x8 ([kernel.kallsyms])
            perf  8562 [000] 347303.578861:         11   cycles:  ffffffff9a477308 native_write_msr+0x8 ([kernel.kallsyms])
            perf  8562 [001] 347303.578903:          1   cycles:  ffffffff9a477308 native_write_msr+0x8 ([kernel.kallsyms])
            perf  8562 [001] 347303.578905:          1   cycles:  ffffffff9a477308 native_write_msr+0x8 ([kernel.kallsyms])
            perf  8562 [001] 347303.578906:         15   cycles:  ffffffff9a477308 native_write_msr+0x8 ([kernel.kallsyms])
            perf  8562 [002] 347303.578952:          1   cycles:  ffffffff9a477308 native_write_msr+0x8 ([kernel.kallsyms])
            perf  8562 [002] 347303.578953:          1   cycles:  ffffffff9a477308 native_write_msr+0x8 ([kernel.kallsyms])

Filter the traced records by hex address ffffffff9a477308.

  root@kbl-ppc:~# ./perf script -S ffffffff9a4dd4ce,ffffffff9a4d2de9,ffffffff9a6bf9f4
            perf  8562 [001] 347303.578911:     311706   cycles:  ffffffff9a6bf9f4 __kmalloc_node+0x204 ([kernel.kallsyms])
            perf  8562 [002] 347303.578960:     354477   cycles:  ffffffff9a4d2de9 sched_setaffinity+0x49 ([kernel.kallsyms])
            perf  8562 [003] 347303.579015:     450958   cycles:  ffffffff9a4dd4ce dequeue_task_fair+0x1ae ([kernel.kallsyms])

Filter the traced records by hex address ffffffff9a4dd4ce, ffffffff9a4d2de9, ffffffff9a6bf9f4.

  root@kbl-ppc:~# ./perf script -S ffffffff9a477309 --addr-range 16
            perf  8562 [000] 347303.578863:        291   cycles:  ffffffff9a47730a native_write_msr+0xa ([kernel.kallsyms])
            perf  8562 [001] 347303.578907:        411   cycles:  ffffffff9a47730a native_write_msr+0xa ([kernel.kallsyms])
            perf  8562 [002] 347303.578956:        462   cycles:  ffffffff9a47730f native_write_msr+0xf ([kernel.kallsyms])
            perf  8562 [003] 347303.579010:        497   cycles:  ffffffff9a47730f native_write_msr+0xf ([kernel.kallsyms])
            perf  8562 [004] 347303.579059:        429   cycles:  ffffffff9a47730f native_write_msr+0xf ([kernel.kallsyms])
            perf  8562 [005] 347303.579109:        408   cycles:  ffffffff9a47730a native_write_msr+0xa ([kernel.kallsyms])
            perf  8562 [006] 347303.579159:        460   cycles:  ffffffff9a47730f native_write_msr+0xf ([kernel.kallsyms])
            perf  8562 [007] 347303.579213:        436   cycles:  ffffffff9a47730f native_write_msr+0xf ([kernel.kallsyms])

Filter the traced records from address range [ffffffff9a477309, ffffffff9a477309 + 15].

  root@kbl-ppc:~# ./perf script -S "ffffffff9b163046,rcu_nmi_exit"
            perf  8562 [004] 347303.579060:      12013   cycles:  ffffffff9b163046 exc_nmi+0x166 ([kernel.kallsyms])
            perf  8562 [007] 347303.579214:      12138   cycles:  ffffffff9b165944 rcu_nmi_exit+0x34 ([kernel.kallsyms])

Filter by address + symbol

Signed-off-by: Jin Yao <yao.jin@linux.intel.com>
Tested-by: Arnaldo Carvalho de Melo <acme@redhat.com>
Cc: Alexander Shishkin <alexander.shishkin@linux.intel.com>
Cc: Andi Kleen <ak@linux.intel.com>
Cc: Jin Yao <yao.jin@intel.com>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Kan Liang <kan.liang@linux.intel.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Link: http://lore.kernel.org/lkml/20210207080935.31784-2-yao.jin@linux.intel.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2021-02-08 17:09:11 -03:00
..
android.txt perf tools: Update android build documentation 2016-07-04 20:27:27 -03:00
asciidoc.conf perf docs: Allow man page date to be specified 2019-09-27 09:26:14 -03:00
asciidoctor-extensions.rb perf Documentation: Support for asciidoctor 2018-04-26 13:47:10 -03:00
build-xed.txt perf script: Add --insn-trace for instruction decoding 2018-10-24 15:29:50 -03:00
Build.txt perf tools: Add doc about how to build perf with Asan and UBSan 2019-03-19 16:52:04 -03:00
callchain-overhead-calculation.txt perf tools: Document --children option in more detail 2015-04-29 10:38:06 -03:00
db-export.txt perf db-export: Add brief documentation 2019-06-05 09:47:57 -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 intel-pt: Update intel-pt.txt file with new location of the documentation 2020-03-11 11:00:33 -03:00
itrace.txt perf auxtrace: Add itrace option '-M' for memory events 2020-11-11 12:24:51 -03:00
jit-interface.txt perf symbols: Add description of JIT interface 2012-08-13 14:55:02 -03:00
jitdump-specification.txt perf docs: Correct and clarify jitdump spec 2019-09-30 17:29:51 -03:00
Makefile perf doc: allow ASCIIDOC_EXTRA to be an argument 2020-04-18 09:05:00 -03:00
manpage-1.72.xsl
manpage-base.xsl
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-suppress-sp.xsl
perf-annotate.txt perf tools: Support --prefix/--prefix-strip 2020-01-14 12:02:19 -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: Add basic syscall benchmark 2020-07-28 08:50:48 -03:00
perf-buildid-cache.txt perf buildid-cache: Add --debuginfod option to specify a server to fetch debug files 2020-12-28 12:20:39 -03:00
perf-buildid-list.txt perf report: Accept fifos as input file 2011-12-23 17:01:03 -02:00
perf-c2c.txt perf c2c: Update documentation for metrics reorganization 2020-10-15 12:02:12 -03:00
perf-config.txt perf buildid-cache: Add --debuginfod option to specify a server to fetch debug files 2020-12-28 12:20:39 -03:00
perf-data.txt perf data: Add support to store time of day in CTF data conversion 2020-08-06 09:43:37 -03:00
perf-diff.txt perf diff: Support hot streams comparison 2020-10-14 13:34:48 -03:00
perf-evlist.txt perf evlist: Document missing --force option 2017-11-16 14:50:07 -03:00
perf-ftrace.txt perf: ftrace: Add filter support for option -F/--funcs 2020-09-04 16:11:16 -03:00
perf-help.txt
perf-inject.txt perf inject: Add --buildid-all option 2020-10-13 11:01:42 -03:00
perf-intel-pt.txt perf intel-pt: Improve PT documentation slightly 2020-10-14 13:14:40 -03:00
perf-kallsyms.txt perf tools: Correct title markers for asciidoctor 2018-03-07 10:26:32 -03:00
perf-kmem.txt perf kmem: Document a missing option & an argument 2018-02-16 14:55:42 -03:00
perf-kvm.txt perf kvm: Clarify the 'perf kvm' -i and -o command line options 2019-12-02 15:38:59 -03:00
perf-list.txt perf tools: Add support for exclusive groups/events 2020-10-14 12:24:28 -03:00
perf-lock.txt perf lock: Document missing options 2017-11-16 14:50:04 -03:00
perf-mem.txt perf mem: Support data page size 2021-01-20 14:34:20 -03:00
perf-probe.txt perf-probe: Add user memory access attribute support 2019-05-25 23:04:42 -04:00
perf-record.txt perf tools: Add 'ping' control command 2021-01-20 14:34:21 -03:00
perf-report.txt perf report: Support instruction latency 2021-02-08 16:25:00 -03:00
perf-sched.txt perf sched timehist: Add support for filtering on CPU 2020-01-06 11:46:09 -03:00
perf-script-perl.txt perf tools: Correct title markers for asciidoctor 2018-03-07 10:26:32 -03:00
perf-script-python.txt perf script python: Add dict fields introduction to Documentation 2018-06-06 15:40:10 -03:00
perf-script.txt perf script: Support filtering by hex address 2021-02-08 17:09:11 -03:00
perf-stat.txt perf stat: Support L2 Topdown events 2021-02-08 16:25:00 -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: Document missing --force option 2017-11-16 14:50:06 -03:00
perf-top.txt perf tools: Add optional support for libpfm4 2020-05-29 16:51:38 -03:00
perf-trace.txt perf trace: Introduce --errno-summary 2019-10-15 13:03:49 -03:00
perf-version.txt perf version: Add man page 2018-04-02 13:52:23 -03:00
perf.data-directory-format.txt perf record: Put a copy of kcore into the perf.data directory 2019-11-06 15:43:05 -03:00
perf.data-file-format.txt perf header: Store clock references for -k/--clockid option 2020-08-06 09:35:06 -03:00
perf.txt perf docs: Improve help information in perf.txt 2020-09-17 16:03:31 -03:00
perfconfig.example perf config: Show default report configuration in example and docs 2016-09-01 09:44:13 -03:00
security.txt perf docs: Introduce security.txt file to document related issues 2020-05-28 10:03:26 -03:00
tips.txt perf tools: Fix typos / broken sentences 2019-07-02 16:08:16 -03:00
topdown.txt perf tools: Update topdown documentation for Sapphire Rapids 2021-02-08 16:25:00 -03:00