Re: [PATCH v6 1/7] perf tools: Add 'perf-config' command

From: Taeung Song
Date: Thu Oct 01 2015 - 01:24:33 EST


Hi, Arnaldo

Thanks for your review


> On Sep 28, 2015, at 11:01 PM, Arnaldo Carvalho de Melo <arnaldo.melo@xxxxxxxxx> wrote:
>
> Em Wed, Sep 23, 2015 at 03:57:01PM +0900, Taeung Song escreveu:
>> The perf configuration file contains many variables which can make
>> the perf command's action more effective.
>> But looking through state of configuration is difficult and there's no knowing
>> what kind of other variables except variables in perfconfig.example exist.
>> So This patch adds 'perf-config' command with '--list' option and a document for it.
>>
>> perf config [options]
>>
>> display current perf config variables.
>> # perf config
>> or
>> # perf config -l | --list
>>
>> Signed-off-by: Taeung Song <treeze.taeung@xxxxxxxxx>
>> ---
>> tools/perf/Build | 1 +
>> tools/perf/Documentation/perf-config.txt | 381 +++++++++++++++++++++++++++++++
>> tools/perf/builtin-config.c | 62 +++++
>> tools/perf/builtin.h | 1 +
>> tools/perf/command-list.txt | 1 +
>> tools/perf/perf.c | 1 +
>> 6 files changed, 447 insertions(+)
>> create mode 100644 tools/perf/Documentation/perf-config.txt
>> create mode 100644 tools/perf/builtin-config.c
>>
>> diff --git a/tools/perf/Build b/tools/perf/Build
>> index 7223745..2c7aaf2 100644
>> --- a/tools/perf/Build
>> +++ b/tools/perf/Build
>> @@ -1,5 +1,6 @@
>> perf-y += builtin-bench.o
>> perf-y += builtin-annotate.o
>> +perf-y += builtin-config.o
>> perf-y += builtin-diff.o
>> perf-y += builtin-evlist.o
>> perf-y += builtin-help.o
>> diff --git a/tools/perf/Documentation/perf-config.txt b/tools/perf/Documentation/perf-config.txt
>> new file mode 100644
>> index 0000000..a3a12cc
>> --- /dev/null
>> +++ b/tools/perf/Documentation/perf-config.txt
>> @@ -0,0 +1,381 @@
>> +perf-config(1)
>> +==============
>> +
>> +NAME
>> +----
>> +perf-config - Get and set variables in a configuration file.
>> +
>> +SYNOPSIS
>> +--------
>> +[verse]
>> +'perf config' -l | --list
>> +
>> +DESCRIPTION
>> +-----------
>> +You can manage variables in a configuration file with this command.
>> +
>> +OPTIONS
>> +-------
>> +
>> +-l::
>> +--list::
>> + Show current config variables with key and value into each sections.
>
> Show current config variables, name and value, for all sections.
>
>> +
>> +CONFIGURATION FILE
>> +------------------
>> +
>> +The Perf configuration file contains many variables which can make
>> +the perf command's action more effective.
>> +The '$HOME/.perfconfig' file is used to store a per-user configuration.
>> +The file '$(sysconfdir)/perfconfig' can be used to
>> +store a system-wide default configuration.
>> +
>> +The variables are divided into sections. In each section, the variables
>> +can are composed of a key and value.
>
> "can are" -> "that are"
>
>> +
>> +Syntax
>> +~~~~~~
>> +
>> +The file consists of sections and names. A section begins with
>> +the name of the section in square brackets and continues until the next
>
> The file consists of sections. A section startas with its name
> surrounded by square brackers and continues till the next section
> begins.
>
>> +section begins. Each variable have to belong to some section, which means
>> +there must be a section header before the first setting of a variable, as below:
>
> Each variable belongs to a section, which means that there must be a
> section header before the first variable, as below:
>
>> +Each variable are in the form 'name = value'.
>> +
>> + [section]
>> + name1 = value1
>> + name2 = value2
>> +
>> +Section names are case sensitive and can contain any characters except
>> +newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`,
>
> double quote
>
>> +respectively). Section headers can't span multiple
>> +lines. Variables may belong directly to a section.
>
> ? They "may" or they "must"? what means "belong directly to a sectionâ?

I meant a section can contain variables or not.
But I think the sentence "Variables may belong directly to a sectionâ isnât needed.

>
>> +
>> +Example
>> +~~~~~~~
>> +
>> +Given a $HOME/.perfconfig like this:
>> +
>> +#
>> +# This is the config file, and
>> +# a '#' and ';' character indicates a comment
>> +#
>> +
>> +[colors]
>> + # Color variables
>> + top = red, default
>> + medium = green, default
>> + normal = lightgray, default
>> + selected = white, lightgray
>> + code = blue, default
>> + addr = magenta, default
>> + root = white, blue
>> +
>> +[tui]
>> + # Defaults if linked with libslang
>> + report = on
>> + annotate = on
>> + top = on
>> +
>> +[buildid]
>> + # Default, disable using /dev/null
>> + dir = ~/.debug
>> +
>> +[annotate]
>> + # Defaults
>> + hide_src_code = false
>> + use_offset = true
>> + jump_arrows = true
>> + show_nr_jumps = false
>> +
>> +[help]
>> + # Format can be man, info, web or html
>> + format = man
>> + autocorrect = 0
>> +
>> +[ui]
>> + show-headers= true
>> +
>> +[call-graph]
>> + # fp (framepointer), dwarf
>> + record-mode = fp
>> + print-type = graph
>> + order = caller
>> + sort-key = function
>> +
>> +Variables
>> +~~~~~~~~~
>> +
>> +colors.*::
>> + Color variables can customize colors of the output which is printed out
>> + from âreportâ, âtopâ, âannotateâ on tui.
>> + Color variables are composed of foreground and background
>> + and should have two values for them. If you want to keep as colors
>
> "and should have two values, comma separated. (please provide an example
> of setting one of those variables).
>
>> + of your terminal, you should use âdefaultâ for the color value.
>
> If you want to keep the background or the foreground color set for your
> terminal, replace the desired value with 'default'. For instance:
>
> (provide an example of setting just the foreground or the background,
> with 'default' for the terminal color that should be used
>
>> + The color names that can be used are:
>
> Shorter:
>
> "Avaliable colors:"
>
>> + red, green, default, black, blue, white, magenta, lightgray
>> +
>> + colors.top::
>> + âtopâ means a overhead percentage which is more than 5%.
>> + And values of this variable specify colors of percentage.
>> + Basic key values are foreground-color âredâ and
>> + background-color âdefaultâ.
>> + colors.medium::
>> + âmediumâ means a overhead percentage which has more than 0.5%.
>> + Default values are âgreenâ and âdefaultâ.
>> + colors.normal::
>> + ânormalâ means the rest of overhead percentages
>> + except âtopâ, âmediumâ, âselectedâ.
>> + Default values are âlightgrayâ and âdefaultâ.
>> + colors.selected::
>> + This selects the colors for the current entry in a list of entries
>> + from sub-commands (top,report,annotate).
>> + Default values are âwhiteâ and âlightgrayâ.
>> + colors.code::
>> + Colors for arrows and lines in jumps on assembly code listings
>> + such as âjnsâ,âjmpâ,âjaneâ,etc. Default values are âblueâ, âdefaultâ.
>> + colors.addr::
>> + This selects colors for addresses from âannotateâ.
>> + Default values are âmagentaâ, âdefaultâ.
>> + colors.root::
>> + Colors for headers in the output of a sub-command âtopâ.
>> + Default values are âwhiteâ, âblueâ.
>> +
>> +tui.*::
>> + A boolean value that controls launching TUI browser for each subcommand.
>
> A boolean value that controls if the TUI browser will be used
> for subcomands having that UI.
>
>> + By default, TUI is enabled if perf detects the required library during build
>> + and this config option can control it. Available subcommands are 'top',
>> + 'report' and 'annotate'.
>> +
>> +gtk.*::
>> + A boolean value that controls launching GTK+2 GUI browser for
>> + each subcommand. By default, TUI is enabled if perf detects the
>
> Use TUI wording suggested above
>
>> + required library during build and this config option can control it.
>> + Available subcommands are 'top', 'report' and 'annotate'.
>> +
>> +buildid.*::
>> + buildid.dir::
>> + Each executable or shared library built with each program is assigned
>> + a unique identification as build-id. The option means a path where
>> + build-id information can be saved.
>
> Each executable and shared library in modern distributions comes with a
> content based identified that, if available, will be inserted in a
> 'perf.data' file header to, at analysis time find what is needed to do
> symbol resolution, code anotation, etc.
>
> The recording tools also stores a hard link or copy in a per-user
> directory, $HOME/.debug/, of binaries, shared libraries, /proc/kallsyms
> and /proc/kcore files to be used at analysis time.
>
> The buildid.dir variable can be used to either change this directory
> cache location, or to disable it altogether.
>
> ---
> find out how to disable it, iirc, its a matter of testing if setting
> buildid.dir to /dev/null works
> Yeah, it works:
>
> [acme@zoo linux]$ ls -la ~/.debug/
> ls: cannot access /home/acme/.debug/: No such file or directory
> [acme@zoo linux]$ perf record usleep 1
> [ perf record: Woken up 1 times to write data ]
> [ perf record: Captured and wrote 0.016 MB perf.data (7 samples) ]
> [acme@zoo linux]$ ls -la ~/.debug/
> ls: cannot access /home/acme/.debug/: No such file or directory
> [acme@zoo linux]$ cat ~/.perfconfig
> [buildid]
> dir = /dev/null
> [acme@zoo linux]$

So.. setting buildid.dir to /dev/null hasnât problems ?
Do I just add a description to disable it by â/dev/nullâ ?

Thanks,
Taeung

>
>> + The default is $HOME/.debug
>> +
>> +annotate.*::
>> + Thereâre options which work with a âannotateâ sub-command.
>> + This options is 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 of itself,
>
> No need for "of itself"
>
>> + this option let âannotateâ print a list of assembly code with the source code.
> lets to print
>
> Getting sidetracked, hope this helps.
>
> - Arnaldo
>
>> + For example, letâs see a part of a program. Thereâre four lines.
>> + If this option is âfalseâ, 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 âtrueâ, 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.
>> + If a base address is 0XFFFFFFFF81624d50 as below,
>> +
>> + ffffffff81624d50 <load0>
>> +
>> + a address on assembly code has a specific absolute address as below
>> +
>> + ffffffff816250b8:â mov 0x8(%r14),%rdi
>> +
>> + but if use_offset is âtrueâ, a address subtracted from a base address is printed.
>> + The default is true.
>> +
>> + 368:â mov 0x8(%r14),%rdi
>> +
>> + annotate.jump_arrows::
>> + Thereâre 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.
>> +
>> + â1 1382: movb $0x1,-0x270(%rbp)
>> +
>> +help.*::
>> + help.format:: = man
>> + A format of manual page can be âmanâ, âinfoâ, âwebâ or âhtmlâ.
>> + âmanâ is default.
>> + help.autocorrect:: = 0
>> + Automatically correct and execute mistyped commands after
>> + waiting for the given number of deciseconds (0.1 sec).
>> + Let's see a example. If a mistyped sub-command is executed like 'perf mistyped-command'
>> + and this option is 0, the output is as below.
>> +
>> + perf: 'mistyped-command' is not a perf-command. See 'perf --helpâ.
>> +
>> + Or if this option is more than 1, the output can be such as.
>> +
>> + WARNING: You called a perf program named 'mistyped-command', which does not exist.
>> + Continuing under the assumption that you meant 'with-kcore'
>> + in 0.1 seconds automatically...
>> + Usage: perf-with-kcore <perf sub-command> <perf.data directory> [<sub-command options> [ -- <workload>]]
>> + <perf sub-command> can be record, script, report or inject
>> + or: perf-with-kcore fix_buildid_cache_permissions
>> +
>> +hist.*::
>> + hist.percentage::
>> + This option control a way to calcurate overhead of filtered entries -
>> + that means the value of this option is effective only if there's a
>> + filter (by comm, dso or symbol name). Suppose a following example:
>> +
>> + Overhead Symbols
>> + ........ .......
>> + 33.33% foo
>> + 33.33% bar
>> + 33.33% baz
>> +
>> + This is an original overhead and we'll filter out the first 'foo'
>> + entry. The value of 'relative' would increase the overhead of 'bar'
>> + and 'baz' to 50.00% for each, while 'absolute' would show their
>> + current overhead (33.33%).
>> +
>> +ui.*::
>> + ui.show-headers::
>> + Thereâre columns as header âOverheadâ, âChildrenâ, âShared Objectâ, âSymbolâ, âselfâ.
>> + If this option is false, they are hiden.
>> +
>> +call-graph.*::
>> + When sub-commands âtopâ and âreportâ work with -g/â-children
>> + thereâre options in control of call-graph.
>> +
>> + call-graph.record-mode::
>> + The record-mode can be âfpâ (frame pointer) and âdwarfâ.
>> + The value of 'dwarf' is effective only if perf detect needed library
>> + (libunwind or a recent version of libdw). Also it doesn't *require*
>> + the dump-size option since it can use the default value of 8192 if
>> + missing.
>> +
>> + call-graph.dump-size::
>> + The size of stack to dump in order to do post-unwinding. Default is 8192 (byte).
>> + When using dwarf into record-mode this option should have a value.
>> +
>> + call-graph.print-type::
>> + The print-types can be graph (graph absolute), fractal (graph relative), flat.
>> + This option controls a way to show overhead for each callchain entry.
>> + Suppose a following example.
>> +
>> + Overhead Symbols
>> + ........ .......
>> + 40.00% foo
>> + |
>> + --- foo
>> + |
>> + |--50.00%-- bar
>> + | main
>> + |
>> + --50.00%-- baz
>> + main
>> +
>> + This output is a default format which is 'fractal'. The 'foo' came
>> + from 'bar' and 'baz' exactly half and half so 'fractal' shows 50.00%
>> + for each (meaning that it assumes 100% total overhead of 'foo').
>> +
>> + The 'graph' uses absolute overhead value of 'foo' as total so each of
>> + 'bar' and 'baz' callchain will have 20.00% of overhead.
>> +
>> + call-graph.order::
>> + This option controls print order of callchains. The default is
>> + 'callee' which means callee is printed at top and then followed by its
>> + caller and so on. The 'caller' prints it in reverse order.
>> +
>> + call-graph.sort-key::
>> + The callchains are merged if they contain same information.
>> + The sort-key option determines a way to compare the callchains.
>> + A value of 'sort-key' can be 'function' or 'addressâ.
>> + The default is âfunctionâ.
>> +
>> + call-graph.threshold::
>> + When there're many callchains it'd print tons of lines. So perf omits
>> + small callchains under a certain overhead (threshold) and this option
>> + control the threashold. Default is 0.5 (%).
>> +
>> + call-graph.print-limit::
>> + This is another way to control the number of callchains printed for a
>> + single entry. Default is 0 which means no limitation.
>> +
>> +report.*::
>> + report.percent-limit::
>> + This one is mostly same as call-graph.threshold but works for
>> + histogram entries. Entries have overhead lower than this percentage
>> + will not be printed. Default is 0.
>> + If percent-limit is 70, the output which has percentages of
>> + each overhead above 70% can be printed.
>> +
>> + report.queue-size::
>> + option to setup the maximum allocation size for session's
>> + ordered events queue, if not set there's no default limit.
>> +
>> + report.children::
>> + The children means that functions called from another function.
>> + If the option is true, accumulate callchain of children and show total overhead.
>> + Please refer to the perf-report manual.
>> +
>> +top.*::
>> + top.children::
>> + This option means same as report.children.
>> + So it is true, the output of âtopâ is rearranged by each overhead into children group.
>> +
>> +man.*::
>> + man.viewer::
>> + This option can assign a manual tool with which a subcommand 'help' work.
>> + it can used as 'man', 'woman', 'konqueror'. Default value is 'man'.
>> +
>> +pager.*::
>> + pager.<subcommand>::
>> + When a subcommand work as stdio instead of TUI, use pager with it.
>> + Default value is 'true'.
>> +
>> +kmem.*::
>> + kmem.default::
>> + This option can decide which allocator is analyzed between 'slab' and 'page'
>> + without using options '--slab' and '--page'.
>> + Default value is 'slab'.
>> +
>> +SEE ALSO
>> +--------
>> +linkperf:perf[1], linkperf:perf-report[1]
>> diff --git a/tools/perf/builtin-config.c b/tools/perf/builtin-config.c
>> new file mode 100644
>> index 0000000..30b1500
>> --- /dev/null
>> +++ b/tools/perf/builtin-config.c
>> @@ -0,0 +1,62 @@
>> +/*
>> + * builtin-config.c
>> + *
>> + * Copyright (C) 2015, Taeung Song <treeze.taeung@xxxxxxxxx>
>> + *
>> + */
>> +#include "builtin.h"
>> +
>> +#include "perf.h"
>> +
>> +#include "util/cache.h"
>> +#include "util/parse-options.h"
>> +#include "util/util.h"
>> +#include "util/debug.h"
>> +
>> +static const char * const config_usage[] = {
>> + "perf config [options]",
>> + NULL
>> +};
>> +
>> +enum actions {
>> + ACTION_LIST = 1
>> +} actions;
>> +
>> +static struct option config_options[] = {
>> + OPT_GROUP("Action"),
>> + OPT_SET_UINT('l', "list", &actions,
>> + "show current config variables", ACTION_LIST),
>> + OPT_END()
>> +};
>> +
>> +static int show_config(const char *key, const char *value,
>> + void *cb __maybe_unused)
>> +{
>> + if (value)
>> + printf("%s=%s\n", key, value);
>> + else
>> + printf("%s\n", key);
>> +
>> + return 0;
>> +}
>> +
>> +int cmd_config(int argc, const char **argv, const char *prefix __maybe_unused)
>> +{
>> + int ret = 0;
>> +
>> + argc = parse_options(argc, argv, config_options, config_usage,
>> + PARSE_OPT_STOP_AT_NON_OPTION);
>> +
>> + switch (actions) {
>> + case ACTION_LIST:
>> + default:
>> + if (argc) {
>> + pr_err("Error: takes no arguments\n");
>> + parse_options_usage(config_usage, config_options, "l", 1);
>> + return -1;
>> + } else
>> + ret = perf_config(show_config, NULL);
>> + }
>> +
>> + return ret;
>> +}
>> diff --git a/tools/perf/builtin.h b/tools/perf/builtin.h
>> index 3688ad2..3f871b5 100644
>> --- a/tools/perf/builtin.h
>> +++ b/tools/perf/builtin.h
>> @@ -17,6 +17,7 @@ extern int cmd_annotate(int argc, const char **argv, const char *prefix);
>> extern int cmd_bench(int argc, const char **argv, const char *prefix);
>> extern int cmd_buildid_cache(int argc, const char **argv, const char *prefix);
>> extern int cmd_buildid_list(int argc, const char **argv, const char *prefix);
>> +extern int cmd_config(int argc, const char **argv, const char *prefix);
>> extern int cmd_diff(int argc, const char **argv, const char *prefix);
>> extern int cmd_evlist(int argc, const char **argv, const char *prefix);
>> extern int cmd_help(int argc, const char **argv, const char *prefix);
>> diff --git a/tools/perf/command-list.txt b/tools/perf/command-list.txt
>> index 00fcaf8..acc3ea7 100644
>> --- a/tools/perf/command-list.txt
>> +++ b/tools/perf/command-list.txt
>> @@ -9,6 +9,7 @@ perf-buildid-cache mainporcelain common
>> perf-buildid-list mainporcelain common
>> perf-data mainporcelain common
>> perf-diff mainporcelain common
>> +perf-config mainporcelain common
>> perf-evlist mainporcelain common
>> perf-inject mainporcelain common
>> perf-kmem mainporcelain common
>> diff --git a/tools/perf/perf.c b/tools/perf/perf.c
>> index 1fded92..6acbfd5 100644
>> --- a/tools/perf/perf.c
>> +++ b/tools/perf/perf.c
>> @@ -38,6 +38,7 @@ struct cmd_struct {
>> static struct cmd_struct commands[] = {
>> { "buildid-cache", cmd_buildid_cache, 0 },
>> { "buildid-list", cmd_buildid_list, 0 },
>> + { "config", cmd_config, 0 },
>> { "diff", cmd_diff, 0 },
>> { "evlist", cmd_evlist, 0 },
>> { "help", cmd_help, 0 },
>> --
>> 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/