Re: [PATCH] perf tools: Document --children option in more detail

[David Ahern <dsahern@gmail.com>]

On 4/18/15 11:33 AM, Namhyung Kim wrote:
> +It might confusing that the sum of the all children overhead exceeds
> +100%.  But with this enabled, users can find which function has most
> +overhead even if samples are spread over the children.

Can you add more detail on why the sum can exceed 100%?

> +
> +Let me see you an example; there’re three functions like below.

That sentence needs some work and should stay in 3rd person. Maybe 
something like this:

"Consider the following example:"

> +
> +-----------------------
> +void foo(void) {
> +    /* something */
> +}
> +
> +bar(void) {
> +    /* do something */
> +    foo();
> +}
> +
> +int main(void) {
> +    bar()
> +    return 0;
> +}
> +-----------------------
> +
> +In this case 'foo' is a child of 'bar', and 'bar' is an immediate
> +child of 'main' so 'foo' also is a child of 'main'.  In other words,
> +'main' is a parent of 'foo' and 'bar'. and 'bar' is a parent of 'foo'.
> +
> +Suppose all samples are recorded in the 'foo' and 'bar' only.  When
> +you record with callchain you'll see something like below in the usual
> +(self-overhead-only) output of the perf report:
> +
> +----------------------------------
> +Overhead  Symbol
> +........  .....................
> +  60.00%  foo
> +          |
> +          --- foo
> +              bar
> +              main
> +              __libc_start_main
> +
> +  40.00%  bar
> +          |
> +          --- bar
> +              main
> +              __libc_start_main
> +----------------------------------
> +
> +When --children option is enabled, the (self) overhead of children (in
> +this case foo and bar) will be added to its parent to calculate the
> +children overhead.  In this case we'll see somethink like below:

Man pages should avoid contractions, should be in 3rd person and
s/somethink/something/.

"When --children option is enabled, the (self) overhead of children (in 
this case foo and bar) are added to the parent to calculate the children 
overhead. In this case the report could display as:"

> +
> +-------------------------------------------
> +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
> +-------------------------------------------
> +
> +Please note that since v3.16 the children overhead will be shown by
> +default and the output will be sorted by the values, users can disable
> +it by specifing --no-children option on the command line, or by adding
> ++report.children = false+ or +top.children = false+ config option.

Maintain tense. Something like:

"Since v3.16 the children overhead is shown by default and the output is 
sorted by the values. Children overhead is disabled by specifying 
--no-children option on the command line or by adding 'report.children = 
false' or 'top.children = false' in the perfconfig file.

Overall nicely done. Thanks for taking the time to write this up.

David