perf tools: Add -H short option for --hierarchy

I found the hierarchy mode useful, but it's easy to make a typo when
using it.  Let's add a short option for that.

Also update the documentation. :)

Acked-by: Arnaldo Carvalho de Melo <acme@redhat.com>
Link: https://lore.kernel.org/r/20240125055124.1579617-1-namhyung@kernel.org
Signed-off-by: Namhyung Kim <namhyung@kernel.org>

diff --git a/tools/perf/Documentation/perf-report.txt b/tools/perf/Documentation/perf-report.txt
index 38f59ac..d8b863e 100644 (file)
--- a/tools/perf/Documentation/perf-report.txt
+++ b/tools/perf/Documentation/perf-report.txt
@@ -531,8 +531,35 @@ include::itrace.txt[]
 --raw-trace::
        When displaying traceevent output, do not use print fmt or plugins.
 
+-H::
 --hierarchy::
-       Enable hierarchical output.
+       Enable hierarchical output.  In the hierarchy mode, each sort key groups
+       samples based on the criteria and then sub-divide it using the lower
+       level sort key.
+
+       For example:
+       In normal output:
+
+         perf report -s dso,sym
+         # Overhead  Shared Object      Symbol
+             50.00%  [kernel.kallsyms]  [k] kfunc1
+             20.00%  perf               [.] foo
+             15.00%  [kernel.kallsyms]  [k] kfunc2
+             10.00%  perf               [.] bar
+              5.00%  libc.so            [.] libcall
+
+       In hierarchy output:
+
+         perf report -s dso,sym --hierarchy
+         #   Overhead  Shared Object / Symbol
+             65.00%    [kernel.kallsyms]
+               50.00%    [k] kfunc1
+               15.00%    [k] kfunc2
+             30.00%    perf
+               20.00%    [.] foo
+               10.00%    [.] bar
+              5.00%    libc.so
+                5.00%    [.] libcall
 
 --inline::
        If a callgraph address belongs to an inlined function, the inline stack

diff --git a/tools/perf/Documentation/perf-top.txt b/tools/perf/Documentation/perf-top.txt
index 3c202ec..a754875 100644 (file)
--- a/tools/perf/Documentation/perf-top.txt
+++ b/tools/perf/Documentation/perf-top.txt
@@ -261,8 +261,38 @@ Default is to monitor all CPUS.
 --raw-trace::
        When displaying traceevent output, do not use print fmt or plugins.
 
+-H::
 --hierarchy::
-       Enable hierarchy output.
+       Enable hierarchical output.  In the hierarchy mode, each sort key groups
+       samples based on the criteria and then sub-divide it using the lower
+       level sort key.
+
+       For example, in normal output:
+
+         perf report -s dso,sym
+         #
+         # Overhead  Shared Object      Symbol
+         # ........  .................  ...........
+             50.00%  [kernel.kallsyms]  [k] kfunc1
+             20.00%  perf               [.] foo
+             15.00%  [kernel.kallsyms]  [k] kfunc2
+             10.00%  perf               [.] bar
+              5.00%  libc.so            [.] libcall
+
+       In hierarchy output:
+
+         perf report -s dso,sym --hierarchy
+         #
+         #   Overhead  Shared Object / Symbol
+         # ..........  ......................
+             65.00%    [kernel.kallsyms]
+               50.00%    [k] kfunc1
+               15.00%    [k] kfunc2
+             30.00%    perf
+               20.00%    [.] foo
+               10.00%    [.] bar
+              5.00%    libc.so
+                5.00%    [.] libcall
 
 --overwrite::
        Enable this to use just the most recent records, which helps in high core count

diff --git a/tools/perf/builtin-report.c b/tools/perf/builtin-report.c
index f2ed2b7..ccb91fe 100644 (file)
--- a/tools/perf/builtin-report.c
+++ b/tools/perf/builtin-report.c
@@ -1410,7 +1410,7 @@ int cmd_report(int argc, const char **argv)
                    "only show processor socket that match with this filter"),
        OPT_BOOLEAN(0, "raw-trace", &symbol_conf.raw_trace,
                    "Show raw trace event output (do not use print fmt or plugins)"),
-       OPT_BOOLEAN(0, "hierarchy", &symbol_conf.report_hierarchy,
+       OPT_BOOLEAN('H', "hierarchy", &symbol_conf.report_hierarchy,
                    "Show entries in a hierarchy"),
        OPT_CALLBACK_DEFAULT(0, "stdio-color", NULL, "mode",
                             "'always' (default), 'never' or 'auto' only applicable to --stdio mode",

diff --git a/tools/perf/builtin-top.c b/tools/perf/builtin-top.c
index baf1ab0..03cf450 100644 (file)
--- a/tools/perf/builtin-top.c
+++ b/tools/perf/builtin-top.c
@@ -1573,7 +1573,7 @@ int cmd_top(int argc, const char **argv)
                    "add last branch records to call history"),
        OPT_BOOLEAN(0, "raw-trace", &symbol_conf.raw_trace,
                    "Show raw trace event output (do not use print fmt or plugins)"),
-       OPT_BOOLEAN(0, "hierarchy", &symbol_conf.report_hierarchy,
+       OPT_BOOLEAN('H', "hierarchy", &symbol_conf.report_hierarchy,
                    "Show entries in a hierarchy"),
        OPT_BOOLEAN(0, "overwrite", &top.record_opts.overwrite,
                    "Use a backward ring buffer, default: no"),