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

[Arnaldo Carvalho de Melo <acme@kernel.org>]

Em Thu, Apr 09, 2015 at 11:26:30PM +0900, Taeung Song escreveu:
> The perf configuration file contain many variables which can make
> the perf command's action more effective and more skilful.
> 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 '--all' option and a document for it.

Thanks for doing this! Now we need to read it thru, but having more
documentation like this is really nice!

- Arnaldo
 
> Signed-off-by: Taeung Song <treeze.taeung@gmail.com>
> ---
>  tools/perf/Build                            |   1 +
>  tools/perf/Documentation/perf-config.txt    | 433 ++++++++++++++++++++++++++++
>  tools/perf/Documentation/perfconfig.example |  65 ++++-
>  tools/perf/builtin-config.c                 |  68 +++++
>  tools/perf/builtin.h                        |   1 +
>  tools/perf/command-list.txt                 |   1 +
>  tools/perf/perf.c                           |   1 +
>  7 files changed, 559 insertions(+), 11 deletions(-)
>  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 b77370e..3c1f437 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..b251702
> --- /dev/null
> +++ b/tools/perf/Documentation/perf-config.txt
> @@ -0,0 +1,433 @@
> +perf-config(1)
> +==============
> +
> +NAME
> +----
> +perf-config - Get and set variables in configuration file.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +'perf config' -a | --all
> +
> +DESCRIPTION
> +-----------
> +You can manage variables in configuration file with this command.
> +
> +OPTIONS
> +-------
> +
> +-a::
> +--all::
> +	Show all variables with key and value into each sections.
> +
> +CONFIGURATION FILE
> +------------------
> +
> +The Perf configuration file contain many variables which can make
> +the perf command's action more effective, more skilful.
> +The '$HOME/.perfconfig' file is used to store a per-user configuration.
> +The file 'etc/perfconfig' or '$(sysconfdir)/perfconfig' can be used to
> +store a system-wide default configuration.
> +
> +The variables are divided into sections. In each sections, the variables
> +can contain a key and values.
> +
> +Syntax
> +~~~~~~
> +
> +The file consists of sections and subkeys. A section begins with
> +the name of the section in square brackets and continues until the next
> +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 are in the form 'subkey = value'.
> +
> +	[section]
> +		subkey1 = value1
> +		subkey2 = value2
> +
> +Subsection names are case sensitive and can contain any characters except
> +newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`,
> +respectively).  Section headers cannot span multiple
> +lines.  Variables may belong directly to a section or to a given subsection.
> +
> +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 = /root/.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 appoint colors of the output which is printed out
> +	from ‘report’, ‘top’,’annotate’ on tui.
> +	Color variables is composed of foreground and background
> +	and should have two values for them. If you want to set as colors
> +	of your terminal, you should use ‘default’ for color value.
> +        The kind of color which can be used as below.
> +	red, green, default, black, blue, white, magenta, lightgray
> +
> +	colors.top::
> +		‘top’ means a overhead percentage which has more than 5%.
> +		And values of it’s 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 rest of overhead percentages
> +		except ‘top’, ‘medium’, ‘selected’.
> +		Default values are ’lightgray’ and ’default’.
> +	colors.selected::
> +		This appoint colors for forcussed one of the output list
> +		from sub-commands (top,report,annotate).
> +		Default values are ’white’ and ’lightgray’.
> +	colors.code::
> +		Colors for a arrow and lines on jumping by assembly code
> +		such as ‘jns’,’jmp’,’jane’,etc. Default values are ‘blue’, ‘default’.
> +	colors.addr::
> +		This appoint colors for addresses from a sub-command ’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.
> +	By default, TUI is enabled if perf detects a needed 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 a
> +	needed 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.
> +		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,
> +		this option let ‘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 ‘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.
> +		For example, there’re three functions like below.
> +
> +		 void foo(void) {
> +		   /* do something */
> +		 }
> +
> +		 void bar(void) {
> +		   /* do something */
> +		   foo();
> +		 }
> +
> +		 int main(void) {
> +		   bar()
> +		   return 0;
> +		 }
> +
> +		Defaultly the output of sub-commands such as ’top’, ‘report’ and ‘annotate’
> +		depend on a sort of overhead into each functions as below.
> +
> +		Overhead  Symbol
> +		........  .....................
> +		  60.00%  foo
> +		          |
> +		          --- foo
> +		              bar
> +		              main
> +		              __libc_start_main
> +
> +		  40.00%  bar
> +		          |
> +		          --- bar
> +		              main
> +		              __libc_start_main
> +
> +		But if this option is true, the sort is changed into a sort of
> +		overhead into each children group of each function  reciting all functions
> +		from a first parent function till a last child function like below.
> +		And it requires -g/--call-graph option enabled
> +
> +		Children      Self  Symbol
> +		........  ........  ....................
> +		 100.00%     0.00%  __libc_start_main
> +		          |
> +		          --- __libc_start_main
> +
> +		 100.00%     0.00%  main
> +		          |
> +		          --- main
> +		              __libc_start_main
> +
> +		 100.00%    40.00%  bar
> +		          |
> +		          --- bar
> +		              main
> +		              __libc_start_main
> +
> +		  60.00%    60.00%  foo
> +		          |
> +		          --- foo
> +		              bar
> +		              main
> +		              __libc_start_main
> +
> +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::
> +
> +pager.*::
> +	pager.report::
> +	pager
> +
> +SEE ALSO
> +--------
> +linkperf:perf[1]
> diff --git a/tools/perf/Documentation/perfconfig.example b/tools/perf/Documentation/perfconfig.example
> index 767ea24..853aa20 100644
> --- a/tools/perf/Documentation/perfconfig.example
> +++ b/tools/perf/Documentation/perfconfig.example
> @@ -1,29 +1,72 @@
>  [colors]
> -
> -	# These were the old defaults
> -	top = red, lightgray
> -	medium = green, lightgray
> -	normal = black, lightgray
> -	selected = lightgray, magenta
> -	code = blue, lightgray
> -	addr = magenta, lightgray
> +	# There are types of colors which are red,
> +	# green, default, black, blue,
> +	# white, magenta, lightgray
> +	# The default is like below
> +	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 = /root/.debug
>  
>  [annotate]
> -
>  	# Defaults
>  	hide_src_code = false
>  	use_offset = true
>  	jump_arrows = true
>  	show_nr_jumps = false
> +
> +[gtk]
> +	report = off
> +	annotate = off
> +	#top = off
> +
> +[pager]
> +	# That a 'cmd' is true mean to use "pager or less"
> +	cmd = true
> +	report = false
> +	diff = true
> +
> +[help]
> +	# Format can be man, info, web or html
> +	format = man
> +	autocorrect = 0
> +
> +[hist]
> +	# a value of 'percentage' can be 'relative' or 'absolute'
> +	percentage = absolute
> +
> +[ui]
> +	show-headers= true
> +
> +[call-graph]
> +	# fp (framepointer), dwarf
> +	record-mode = fp
> +
> +	# graph (graph absolute), flat, fractal (graph relative)
> +	print-type = fractal
> +
> +	# caller, callee
> +	order = caller
> +
> +	# function, address
> +	sort-key = function
> +
> +[report]
> +	percent-limit = 1
> +	children = false
> +
> +[top]
> +	children = true
> diff --git a/tools/perf/builtin-config.c b/tools/perf/builtin-config.c
> new file mode 100644
> index 0000000..32f8ae6
> --- /dev/null
> +++ b/tools/perf/builtin-config.c
> @@ -0,0 +1,68 @@
> +/*
> + * builtin-config.c
> + *
> + * Copyright (C) 2015, Taeung Song <treeze.taeung@gmail.com>
> + *
> + */
> +#include "builtin.h"
> +
> +#include "perf.h"
> +
> +#include "util/cache.h"
> +#include "util/parse-options.h"
> +#include "util/util.h"
> +#include "util/debug.h"
> +
> +static struct {
> +	bool all_action;
> +} params;
> +
> +static const char * const config_usage[] = {
> +	"perf config [options]",
> +	NULL
> +};
> +static const struct option config_options[] = {
> +	OPT_GROUP("Action"),
> +	OPT_BOOLEAN('a', "all", &params.all_action, "print all configurations"),
> +	OPT_END()
> +};
> +
> +static void check_argc(int argc, int limit)
> +{
> +	if (argc >= limit && argc <= limit)
> +		return;
> +	error("wrong number of arguments");
> +	usage_with_options(config_usage, config_options);
> +}
> +
> +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);
> +	if (argc > 0) {
> +		if (strcmp(argv[0], "-") == 0) {
> +			pr_warning("  Error: '-' is not supported.\n");
> +			usage_with_options(config_usage, config_options);
> +		}
> +	}
> +
> +	if (argc == 0 || params.all_action) {
> +		check_argc(argc, 0);
> +		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 b857fcb..604fa4a 100644
> --- a/tools/perf/perf.c
> +++ b/tools/perf/perf.c
> @@ -37,6 +37,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